A documentation-first development methodology that enables AI agents to understand, build, and maintain complex software projects through structured knowledge capture.
Claude Code is ACP's preferred coding agent provider, however any provider will work out of the box.
- OS: Linux or macOS
- Shell: Bash 4+ (
bash --versionto check) - Git: 2.x+
macOS note: The default
/bin/bashon macOS is 3.2. Homebrew's bash (/opt/homebrew/bin/bashor/usr/local/bin/bash) is typically 5.x and works out of the box.
curl -fsSL https://raw.githubusercontent.com/prmichaelsen/agent-context-protocol/mainline/agent/scripts/acp.install.sh | bashYou can update an existing project via @acp.version-update command or by running the update script directly:
curl -fsSL https://raw.githubusercontent.com/prmichaelsen/agent-context-protocol/mainline/agent/scripts/acp.version-update.sh | bashOr if you have ACP already installed locally:
./agent/scripts/acp.version-update.shThe Agent Context Protocol is a standardized directory structure and documentation pattern that transforms implicit project knowledge into explicit, machine-readable documentation. It provides:
- Design Documents - Architectural decisions and technical specifications
- Milestones - Project phases with clear deliverables
- Tasks - Granular, actionable work items
- Patterns - Reusable architectural and coding patterns
- Progress Tracking - YAML-based progress monitoring
This enables AI agents to pick up where previous agents left off, preserving all context and decisions across sessions.
This will create:
AGENT.md- Complete ACP methodology documentationagent/directory with all template filesagent/scripts/directory with update utilities
Once ACP is installed, use these commands with your AI agent:
Type: @acp.init (or AGENT.md: Initialize)
This will:
- Check for ACP updates
- Read all agent documentation
- Review source code
- Update stale documentation
- Prepare to work on tasks
Type: @acp.proceed (or AGENT.md: Proceed)
This will:
- Continue with current or next task
- Update progress tracking
- Maintain documentation
Type: @acp.resume ⭐ Recommended
This convenient command automatically:
- Initializes context (
@acp.init) - Reviews latest session report
- Continues with next task (
@acp.proceed)
Perfect for starting new sessions or returning after breaks.
Type: @acp.status
This will:
- Display current milestone and progress
- Show current task
- List recent work and next steps
Workflow Commands:
@acp.resume⭐ - Resume work (init + report + proceed)@acp.init- Initialize agent context@acp.proceed- Continue with next task@acp.status- Display project status@acp.sync- Sync documentation with code@acp.validate- Validate ACP structure@acp.report- Generate session report@acp.index- Manage the key file index (list, add, remove, explore, show)
Package Management:
@acp.package-install- Install packages (supports--globalflag)@acp.package-list- List installed packages (supports--globalflag)@acp.package-info- Show package details (supports--globalflag)@acp.package-update- Update packages (supports--globalflag)@acp.package-remove- Remove packages (supports--globalflag)@acp.package-search- Search for packages@acp.package-validate- Validate package structure@acp.package-publish- Publish package@acp.package-create- Create new package
Entity Creation:
@acp.command-create- Create command files@acp.pattern-create- Create pattern files@acp.design-create- Create design documents@acp.task-create- Create task files
Version Commands:
@acp.version-check- Show current ACP version@acp.version-check-for-updates- Check for updates@acp.version-update- Update ACP to latest version
Project Registry:
@acp.project-list- List registered projects@acp.project-set- Switch to a project@acp.project-info- Show project details@acp.project-update- Update project metadata@acp.project-remove- Remove project from registry@acp.projects-sync- Discover unregistered projects
Sessions (Experimental):
@acp.sessions- Manage and view active agent sessions across projects
Git Commands:
@git.commit- Intelligent version-aware commits@git.init- Initialize git repository
See AGENT.md for complete command documentation and methodology.
Install packages globally to ~/.acp/agent/ for package development or global command libraries:
# Install package globally
./agent/scripts/acp.package-install.sh --global https://github.com/user/acp-firebase.git
# Or via command
@acp.package-install --global https://github.com/user/acp-firebase.git
# List global packages
@acp.package-list --global
# Update global packages
@acp.package-update --global firebase
# Remove global packages
@acp.package-remove --global firebaseGlobal vs Local:
- Global: Installed to
~/.acp/agent/, available for discovery in any project - Local: Installed to
./agent/, only available in current project - Precedence: Local packages always override global packages
Use cases for global installation:
- Package development with full ACP tooling
- Common utilities used across many projects
- Building a personal command library
- Experimenting with packages before local installation
Install packages with experimental features:
# Install only stable features (default)
@acp.package-install --repo https://github.com/user/acp-firebase.git
# Install including experimental features
@acp.package-install --repo https://github.com/user/acp-firebase.git --experimentalWhat are experimental features?
- Bleeding-edge features that may change
- Require explicit opt-in via --experimental flag
- Once installed, update normally
See AGENT.md for complete documentation.
ACP includes a weighted key file index (agent/index/) that ensures agents read critical project files before making decisions. Each entry declares a file path, priority weight, and which commands should read it.
# Manage the key file index
@acp.index list # List all indexed key files
@acp.index add <path> # Add a file to the index
@acp.index remove <path> # Remove a file from the indexPackages can ship their own index files (contents.indices in package.yaml), which are automatically installed to agent/index/ and discovered by commands.
See AGENT.md for complete documentation.
ACP includes an automated benchmark system that measures the impact of ACP on AI-driven development. It runs identical tasks with and without ACP, comparing metrics like token usage, code quality, and task completion.
# Run all benchmarks
bash agent/benchmarks/runner/run-benchmark.sh
# Run a specific task
bash agent/benchmarks/runner/run-benchmark.sh --task complex-auth-system
# View HTML reports
bash agent/benchmarks/runner/serve-reports.sh6 benchmark tasks ranging from simple (hello-world) to complex (order pipeline with event-driven refactor). Each task includes automated verification and LLM-based quality evaluation.
See AGENT.md for complete documentation. On-demand CI via GitHub Actions (workflow_dispatch).
Manage multiple ACP projects with the global project registry at ~/.acp/projects.yaml:
# List all registered projects
@acp.project-list
# Switch to a specific project
@acp.project-set my-project
# View current project details
@acp.project-info
# Update project metadata (tags, status, description)
@acp.project-update --tags "typescript,api" --status in_progress
# Discover unregistered projects in ~/.acp/projects/
@acp.projects-sync
# Remove project from registry (keeps files)
@acp.project-remove old-projectKey Features:
- Project Discovery: List and filter projects by type, status, or tags
- Context Switching: Quickly switch between projects
- Metadata Tracking: Track type, status, tags, and relationships
- Auto-Registration: Projects auto-register when created via
@acp.project-create
See AGENT.md for complete documentation.
See these repositories for real-world examples of ACP in action:
- remember-mcp-server - Multi-tenant memory system with vector search
- remember-mcp - Memory management MCP implementation
- agentbase-mcp-server - Agent base server implementation
- agentbase-mcp - Agent base MCP tools
- google-calendar-mcp - Google Calendar integration MCP server
- mcp-auth - Authentication framework for MCP servers
project-root/
├── AGENT.md # ACP documentation (this pattern)
├── agent/ # Agent directory
│ ├── commands/ # Command system
│ │ ├── .gitkeep
│ │ ├── command.template.md # Command template
│ │ ├── acp.init.md # @acp.init
│ │ ├── acp.proceed.md # @acp.proceed
│ │ ├── acp.status.md # @acp.status
│ │ └── ... # More commands
│ │
│ ├── design/ # Design documents
│ │ ├── .gitkeep
│ │ ├── design.template.md # Template for design docs
│ │ └── requirements.md # Your project requirements
│ │
│ ├── milestones/ # Project milestones
│ │ ├── .gitkeep
│ │ ├── milestone-1-{title}.template.md
│ │ └── milestone-1-foundation.md
│ │
│ ├── patterns/ # Architectural patterns
│ │ ├── .gitkeep
│ │ ├── pattern.template.md
│ │ ├── bootstrap.template.md
│ │ └── typescript/ # Language-specific patterns
│ │ └── *.md
│ │
│ ├── tasks/ # Granular tasks
│ │ ├── .gitkeep
│ │ ├── task-1-{title}.template.md
│ │ └── task-1-setup.md
│ │
│ ├── index/ # Key file index
│ │ ├── local.main.yaml # Project's key files
│ │ └── {pkg}.main.yaml # Package-shipped indices
│ │
│ └── progress.yaml # Progress tracking
│
└── (your project files)
ACP provides template files for each document type:
design.template.md- Template for design documentsmilestone-1-{title}.template.md- Template for milestone documentstask-1-{title}.template.md- Template for task documentspattern.template.md- Template for pattern documentsbootstrap.template.md- Template for project bootstrap patternsprogress.template.yaml- Template for progress tracking
Each template includes:
- Section headers with descriptions
- Example content showing proper usage
- Guidance on what to include
- Best practices and conventions
- Documentation is Infrastructure - Treat it with the same care as code
- Explicit Over Implicit - Document everything that matters
- Structure Enables Scale - Organization makes complexity manageable
- Agents Need Context - Provide complete, accessible context
- Progress is Measurable - Track objectively with YAML
- Patterns Ensure Quality - Document and follow best practices
- Knowledge Persists - No more lost tribal knowledge
✅ Use ACP when:
- Complex projects (>1 month)
- Multiple contributors (agents or humans)
- Long-term maintenance required
- Quality and consistency critical
- Knowledge preservation important
❌ Don't use ACP for:
- Trivial scripts (<100 lines)
- One-off prototypes
- Throwaway code
- Simple, well-understood problems
For complete documentation, see AGENT.md, which includes:
- Detailed explanation of each component
- Step-by-step usage instructions
- Best practices and conventions
- Problem-solving patterns
- Real-world examples
Contributions are welcome! Please:
- Follow the existing template structure
- Document your changes in design documents
- Update relevant patterns
- Add examples where helpful
MIT License - See LICENSE for details
- Repository: https://github.com/prmichaelsen/agent-context-protocol
- Issues: https://github.com/prmichaelsen/agent-context-protocol/issues
- Documentation: See AGENT.md
The Agent Context Protocol is not just documentation—it's a development methodology that makes complex software projects tractable for AI agents.