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.
)
Tier Selection:
| Remaining Budget | Tier | Content Depth |
|---|---|---|
| <80 tokens | minimal | Command + one-line purpose |
| 80-299 tokens | standard | + options, usage |
| 300+ tokens | full | + examples, patterns |
Examples:
# Standard primer (200 tokens)
# Minimal primer
# Full primer with project warnings
# JSON output with metadata
# Filter by capability
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_query — Query symbols, files, and domains
- acp_constraints — Check file constraints before modification
- acp_primer — Generate context primers
- acp_expand — Expand variable references
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