ACP CLI
Command-line interface for the AI Context Protocol — index your codebase, generate variables, and manage AI behavioral constraints.
Installation
From crates.io (Recommended)
This installs the acp binary to your Cargo bin directory.
From Homebrew
From npm
Pre-built Binaries
Pre-built binaries for macOS, Linux, and Windows are available on the Releases page.
Building from Source
Quick Start
1. Initialize Your Project
This creates .acp.config.json and optionally bootstraps AI tool configurations (CLAUDE.md, .cursorrules).
2. Index Your Codebase
This generates .acp/acp.cache.json with your codebase structure, symbols, and constraints.
3. Generate Annotations (Optional)
# Preview annotation suggestions
# Apply annotations to files
This analyzes your codebase and suggests ACP annotations based on doc comments and heuristics.
4. Generate Variables
# Or separately:
This creates .acp/acp.vars.json with token-efficient variable definitions.
5. Query the Cache
# Show stats
# Look up a symbol
# List domains
Commands
Global Options
-c, --config <path> Config file path [default: .acp.config.json]
-v, --verbose Enable verbose output
-h, --help Print help
-V, --version Print version
acp init
Initialize a new ACP project with configuration and optional AI tool bootstrapping.
)
)
)
)
Examples:
# Interactive initialization
# Non-interactive with custom patterns
# Skip AI tool bootstrapping
acp install
Install ACP plugins (daemon, MCP server).
)
Examples:
# Install daemon and MCP server
# List installed plugins
# Uninstall a plugin
acp index
Index the codebase and generate .acp/acp.cache.json.
Examples:
# Index current directory
# Index specific directory with vars
# Custom output path
acp annotate
Generate ACP annotations from code analysis and documentation conversion.
)
)
)
)
)
Annotation Levels:
| Level | Includes |
|---|---|
minimal |
@acp:summary only |
standard |
summary, domain, layer, lock |
full |
All annotation types including stability, ai-hint |
Examples:
# Preview annotations for current directory
# Apply annotations to files
# Convert only existing doc comments (no heuristics)
# Generate minimal annotations from JSDoc
# CI mode: fail if coverage below 90%
# JSON output with breakdown
acp review
Review auto-generated annotations (RFC-0003).
)
)
Examples:
# List low-confidence annotations
# Interactive review mode
# Mark specific annotations as reviewed
acp vars
Generate .acp/acp.vars.json from an existing cache.
Example:
acp query
Query the cache for symbols, files, and metadata.
Examples:
# Get symbol info as JSON
# See what calls a function
# List all domains
# Show codebase statistics
acp expand
Expand variable references in text.
)
Examples:
# Expand inline
# Pipe from stdin
|
# Show variable inheritance
Expansion Modes:
| Mode | Description |
|---|---|
none |
Keep $VAR references as-is |
summary |
Replace with summary only |
inline |
Replace with full value |
annotated |
Show **$VAR** → value |
block |
Full formatted block |
interactive |
HTML-like markers for UI |
acp chain
Show variable inheritance chain.
)
Examples:
# Show chain
# Show as tree
acp daemon
Manage the ACP daemon (HTTP REST API).
Examples:
# Start the daemon
# Check status
# View logs
acp attempt
Manage troubleshooting attempts for debugging sessions.
)
Attempt workflow:
# Start debugging
# If it fails
# If it works
# Clean up all failed attempts
Checkpoint workflow:
# Create checkpoint before risky changes
# List checkpoints
# Restore if needed
acp check
Check guardrails for a file.
Example:
Output:
Guardrails check passed
Warnings:
[ai-careful] Extra caution required: security-critical code
Required Actions:
-> flag-for-review - Requires security review
acp revert
Revert changes from an attempt or restore a checkpoint.
Examples:
# Revert a failed attempt
# Restore to checkpoint
acp watch
Watch for file changes and update cache in real-time.
Example:
acp validate
Validate cache or vars files against the schema.
)
Examples:
acp primer
Generate AI bootstrap primers with tiered content selection (RFC-0015).
Automatic Tier Selection:
| Tier | Token Budget | Content |
|---|---|---|
micro |
<300 | Essential safety constraints only |
minimal |
300-449 | Core project context |
standard |
450-699 | Balanced context with conventions |
full |
≥700 | Complete project understanding |
)
)
)
)
Weight Presets:
| Preset | Safety | Efficiency | Accuracy | Use Case |
|---|---|---|---|---|
safe |
2.5 | 0.8 | 1.0 | Security-critical projects |
efficient |
1.2 | 2.0 | 0.9 | Fast iteration, prototyping |
accurate |
1.2 | 0.9 | 2.0 | Precision-critical work |
balanced |
1.5 | 1.0 | 1.0 | Default, general use |
Examples:
# Micro tier primer (~250 tokens)
# Minimal tier primer (~400 tokens)
# Standard tier primer (~600 tokens)
# Full tier primer with MCP capability
# Standalone mode for raw API usage
# List available sections
# Preview what would be selected
# JSON output with tier metadata
Customization:
Create .acp/primer.json to customize:
- Section weights and priorities
- Add project-specific sections
- Disable default sections
- Override templates
acp context
Get operation-specific context for AI agents (RFC-0015).
)
Context Types:
| Operation | Returns |
|---|---|
create |
Naming conventions, import style, similar files |
modify |
Constraints, importers (affected files), symbols |
debug |
Related files, symbol info, hotpaths |
explore |
Project stats, domain overview, key files |
Examples:
# Get context before creating a new file
# Get context before modifying a file
# Get debug context for a symbol
# Explore the codebase structure
# Focus on a specific domain
Configuration
Create .acp.config.json in your project root (or run acp init):
See the config schema for all options.
jq Quick Reference
Query the cache directly with jq:
# Check if you can modify a file
# Get all frozen files
# Find expired hacks
# Get symbol info
# List all domains
# Get files in a domain
# Show codebase stats
MCP Integration
The ACP MCP server provides AI tools with direct access to your codebase context through the Model Context Protocol.
Install and run via:
Or install separately from acp-mcp.
Available MCP Tools:
- acp_get_architecture — Get project overview with domains, files, symbols
- acp_get_file_context — Get detailed context for a specific file
- acp_get_symbol_context — Get symbol info with callers and callees
- acp_get_domain_files — Get files in a domain
- acp_check_constraints — Check file constraints before modification
- acp_get_hotpaths — Get frequently-called symbols
- acp_expand_variable — Expand ACP variable references
- acp_generate_primer — Generate context primers with tier selection
- acp_context — Operation-specific context (create, modify, debug, explore)
IDE Integration
ACP automatically detects your IDE environment and adapts its behavior accordingly.
Supported IDEs:
| IDE | Detection | Notes |
|---|---|---|
| Cursor | CURSOR_* env vars |
Uses .cursorrules |
| VS Code | VSCODE_* env vars |
Uses CLAUDE.md with Cline |
| Cline | CLINE_* env vars |
Extension-provided context |
| JetBrains | JETBRAINS_IDE env var |
IntelliJ, WebStorm, etc. |
| Zed | ZED_* env vars |
Built-in AI integration |
| Claude Code | CLAUDE_CODE env var |
Uses CLAUDE.md |
| Terminal | Default | Raw API usage |
Bootstrap Files:
When you run acp init, it creates IDE-specific bootstrap files:
# Bootstrap for Cursor
# Bootstrap for Claude Code, Cline
# Both include primers and project context
Using Primers with IDEs:
# IDE context (auto-detected) - no --standalone needed
# Raw API usage (e.g., direct Anthropic API calls)
Environment Variables:
| Variable | Purpose |
|---|---|
ACP_NO_IDE_DETECT=1 |
Disable IDE detection |
Example: Cursor Integration
# 1. Initialize project
# 2. Add primer to .cursorrules
# 3. Get context before modifications
Example: Claude Code Integration
# 1. Initialize project
# 2. Add primer to CLAUDE.md
# 3. Use context command for operations
Key Annotations
| Annotation | Purpose | AI Behavior |
|---|---|---|
@acp:lock frozen |
Never modify | Refuses all changes |
@acp:lock restricted |
Explain first | Describes changes before making them |
@acp:lock approval-required |
Ask permission | Waits for explicit approval |
@acp:style <guide> |
Follow style guide | Uses specified conventions |
@acp:ref <url> |
Documentation reference | Can fetch and consult |
@acp:hack |
Temporary code | Tracks for cleanup |
@acp:debug-session |
Debug tracking | Logs attempts for reversal |
Type Annotations (RFC-0008)
Optional type syntax for documenting parameters and return types:
/**
* @acp:fn "authenticate" - User authentication handler
* @acp:template T extends User - User type for response
* @acp:param {string} email - Valid email address
* @acp:param {string} password - Password meeting requirements
* @acp:param {AuthOptions} [options={}] - Optional auth settings
* @acp:returns {Promise<T | null>} - User object or null if failed
*/
async function authenticate<T extends User>(
email: string,
password: string,
options?: AuthOptions
): Promise<T | null> { }
Syntax:
@acp:param {Type} name - directive— Parameter with type@acp:param {Type} [name] - directive— Optional parameter@acp:param {Type} [name=default] - directive— Parameter with default@acp:returns {Type} - directive— Return type@acp:template T extends Constraint - directive— Generic type parameter
Types are optional and stored in the cache's type_info field.
See the Annotation Reference for the complete list.
Related Documentation
- ACP Specification — Complete protocol specification
- JSON Schemas — Schema definitions for all file formats
- Annotation Reference — All annotation types
Contributing
See CONTRIBUTING.md for guidelines.
Security
See SECURITY.md for vulnerability reporting.
License
MIT — see LICENSE