acp-protocol

Crates.io	acp-protocol
lib.rs	acp-protocol
version	0.7.0
created_at	2025-12-17 19:05:47.675989+00
updated_at	2026-01-03 15:16:41.453735+00
description	AI Context Protocol - Token-efficient and context enhancing code documentation for AI systems
homepage
repository	https://github.com/acp-protocol/acp-cli
max_upload_size
id	1990979
size	1,531,959

DavidAD (ddunnock)

documentation

README

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)

cargo install acp-protocol

This installs the acp binary to your Cargo bin directory.

From Homebrew

brew tap acp-protocol/tap
brew install acp

From npm

npm install -g @acp-protocol/acp

Pre-built Binaries

Pre-built binaries for macOS, Linux, and Windows are available on the Releases page.

Building from Source

git clone https://github.com/acp-protocol/acp-cli.git
cd acp-cli
cargo build --release
cargo install --path .

Quick Start

1. Initialize Your Project

cd your-project
acp init

This creates .acp.config.json and optionally bootstraps AI tool configurations (CLAUDE.md, .cursorrules).

2. Index Your Codebase

acp index

This generates .acp/acp.cache.json with your codebase structure, symbols, and constraints.

3. Generate Annotations (Optional)

# Preview annotation suggestions
acp annotate

# Apply annotations to files
acp annotate --apply

This analyzes your codebase and suggests ACP annotations based on doc comments and heuristics.

4. Generate Variables

acp index --vars
# Or separately:
acp vars

This creates .acp/acp.vars.json with token-efficient variable definitions.

5. Query the Cache

# Show stats
acp query stats

# Look up a symbol
acp query symbol validateSession

# List domains
acp query 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.

acp init [OPTIONS]

Options:
  -f, --force              Force overwrite existing config
      --include <PATTERN>  File patterns to include (can specify multiple)
      --exclude <PATTERN>  File patterns to exclude (can specify multiple)
  -o, --output <PATH>      Config file output path [default: .acp.config.json]
      --no-bootstrap       Skip AI tool bootstrap (CLAUDE.md, .cursorrules, etc.)
  -y, --yes                Skip interactive prompts (use defaults + CLI args)

Examples:

# Interactive initialization
acp init

# Non-interactive with custom patterns
acp init -y --include "src/**/*" --exclude "**/test/**"

# Skip AI tool bootstrapping
acp init --no-bootstrap

`acp install`

Install ACP plugins (daemon, MCP server).

acp install <TARGETS>... [OPTIONS]

Arguments:
  TARGETS    Plugins to install (daemon, mcp)

Options:
  -f, --force              Force reinstall
      --version <VERSION>  Specific version [default: latest]
      --list               List installed plugins
      --uninstall          Uninstall specified plugins

Examples:

# Install daemon and MCP server
acp install daemon mcp

# List installed plugins
acp install --list

# Uninstall a plugin
acp install daemon --uninstall

`acp index`

Index the codebase and generate .acp/acp.cache.json.

acp index [ROOT] [OPTIONS]

Arguments:
  ROOT    Root directory to index [default: .]

Options:
  -o, --output <path>    Output cache file [default: .acp/acp.cache.json]
      --vars             Also generate vars file

Examples:

# Index current directory
acp index

# Index specific directory with vars
acp index ./src --vars

# Custom output path
acp index -o build/cache.json

`acp annotate`

Generate ACP annotations from code analysis and documentation conversion.

acp annotate [PATH] [OPTIONS]

Arguments:
  PATH    Path to analyze (file or directory) [default: .]

Options:
      --apply                   Apply changes to files (default: preview only)
      --convert                 Convert-only mode: only use doc comment conversion
      --from <SOURCE>           Source documentation standard [default: auto]
                                Values: auto, jsdoc, tsdoc, docstring, rustdoc, godoc, javadoc
      --level <LEVEL>           Annotation generation level [default: standard]
                                Values: minimal, standard, full
      --format <FORMAT>         Output format [default: diff]
                                Values: diff, json, summary
      --filter <PATTERN>        Filter files by glob pattern
      --files-only              Only annotate files (skip symbols)
      --symbols-only            Only annotate symbols (skip file-level)
      --check                   Exit with error if coverage below threshold (CI mode)
      --min-coverage <PERCENT>  Minimum coverage threshold [default: 80]
  -j, --workers <N>             Number of parallel workers [default: CPU count]

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
acp annotate

# Apply annotations to files
acp annotate --apply

# Convert only existing doc comments (no heuristics)
acp annotate --convert --apply

# Generate minimal annotations from JSDoc
acp annotate --from jsdoc --level minimal

# CI mode: fail if coverage below 90%
acp annotate --check --min-coverage 90

# JSON output with breakdown
acp annotate --format json

`acp review`

Review auto-generated annotations (RFC-0003).

acp review <SUBCOMMAND> [OPTIONS]

Subcommands:
  list         List annotations needing review
  mark         Mark annotations as reviewed
  interactive  Interactive review mode

Options:
      --source <SOURCE>          Filter by source (explicit, converted, heuristic, refined, inferred)
      --confidence <EXPR>        Filter by confidence (e.g., "<0.7", ">=0.9")
      --cache <PATH>             Cache file path [default: .acp/acp.cache.json]
      --json                     Output as JSON

Examples:

# List low-confidence annotations
acp review list --confidence "<0.7"

# Interactive review mode
acp review interactive

# Mark specific annotations as reviewed
acp review mark --source heuristic

`acp vars`

Generate .acp/acp.vars.json from an existing cache.

acp vars [OPTIONS]

Options:
  -c, --cache <path>     Cache file to read [default: .acp/acp.cache.json]
  -o, --output <path>    Output vars file [default: .acp/acp.vars.json]

Example:

acp vars -c build/cache.json -o build/vars.json

`acp query`

Query the cache for symbols, files, and metadata.

acp query <SUBCOMMAND> [OPTIONS]

Options:
  -c, --cache <path>    Cache file [default: .acp/acp.cache.json]

Subcommands:
  symbol <name>     Query a symbol by name
  file <path>       Query a file by path
  callers <symbol>  Get callers of a symbol
  callees <symbol>  Get callees of a symbol
  domains           List all domains
  domain <name>     Query a specific domain
  hotpaths          List frequently-called symbols
  stats             Show aggregate statistics

Examples:

# Get symbol info as JSON
acp query symbol validateSession

# See what calls a function
acp query callers handleRequest

# List all domains
acp query domains

# Show codebase statistics
acp query stats

`acp expand`

Expand variable references in text.

acp expand [TEXT] [OPTIONS]

Arguments:
  TEXT    Text to expand (reads from stdin if omitted)

Options:
  -m, --mode <mode>     Expansion mode [default: annotated]
                        Values: none, summary, inline, annotated, block, interactive
      --vars <path>     Vars file [default: .acp/acp.vars.json]
      --chains          Show inheritance chains

Examples:

# Expand inline
acp expand "Check \$SYM_VALIDATE_SESSION"

# Pipe from stdin
echo "See \$ARCH_AUTH_FLOW" | acp expand --mode block

# Show variable inheritance
acp expand "\$SYM_HANDLER" --chains

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.

acp chain <NAME> [OPTIONS]

Arguments:
  NAME    Variable name (with or without $)

Options:
      --vars <path>    Vars file [default: .acp/acp.vars.json]
      --tree           Display as tree

Examples:

# Show chain
acp chain SYM_AUTH_HANDLER

# Show as tree
acp chain $ARCH_PAYMENT --tree

`acp daemon`

Manage the ACP daemon (HTTP REST API).

acp daemon <SUBCOMMAND>

Subcommands:
  start   Start the ACP daemon
  stop    Stop the ACP daemon
  status  Check daemon status
  logs    Show daemon logs

Examples:

# Start the daemon
acp daemon start

# Check status
acp daemon status

# View logs
acp daemon logs

`acp attempt`

Manage troubleshooting attempts for debugging sessions.

acp attempt <SUBCOMMAND>

Subcommands:
  start <id>          Start a new attempt
  list                List attempts
  fail <id>           Mark attempt as failed
  verify <id>         Mark attempt as verified (success)
  revert <id>         Revert an attempt's changes
  cleanup             Clean up all failed attempts
  checkpoint <name>   Create a checkpoint
  checkpoints         List all checkpoints
  restore <name>      Restore to a checkpoint

Attempt workflow:

# Start debugging
acp attempt start auth-fix-001 -f "BUG-123" -d "Fixing 401 errors"

# If it fails
acp attempt fail auth-fix-001 --reason "Broke login flow"
acp attempt revert auth-fix-001

# If it works
acp attempt verify auth-fix-001

# Clean up all failed attempts
acp attempt cleanup

Checkpoint workflow:

# Create checkpoint before risky changes
acp attempt checkpoint before-refactor -f src/auth.ts -f src/session.ts

# List checkpoints
acp attempt checkpoints

# Restore if needed
acp attempt restore before-refactor

`acp check`

Check guardrails for a file.

acp check <FILE> [OPTIONS]

Arguments:
  FILE    File to check

Options:
  -c, --cache <path>    Cache file [default: .acp/acp.cache.json]

Example:

acp check src/auth/session.ts

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.

acp revert [OPTIONS]

Options:
      --attempt <id>        Attempt ID to revert
      --checkpoint <name>   Checkpoint name to restore

Examples:

# Revert a failed attempt
acp revert --attempt auth-fix-001

# Restore to checkpoint
acp revert --checkpoint before-refactor

`acp watch`

Watch for file changes and update cache in real-time.

acp watch [ROOT]

Arguments:
  ROOT    Directory to watch [default: .]

Example:

acp watch ./src

`acp validate`

Validate cache or vars files against the schema.

acp validate <FILE>

Arguments:
  FILE    File to validate (.acp/acp.cache.json or .acp/acp.vars.json)

Examples:

acp validate .acp/acp.cache.json
acp validate .acp/acp.vars.json

`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

acp primer [OPTIONS]

Core Options:
  -b, --budget <N>           Token budget determines tier [default: 200]
      --capabilities <caps>  Filter by capabilities (shell, mcp, editor)
  -f, --format <type>        Output format: markdown, compact, json, text [default: markdown]
      --json                 Output as JSON with metadata
      --standalone           Standalone mode for raw API usage (not needed in IDEs)

Selection Options:
  -p, --preset <name>        Weight preset: safe, efficient, accurate, balanced [default: balanced]
      --include <ids>        Force include section IDs (comma-separated)
      --exclude <ids>        Exclude section IDs (comma-separated)
      --categories <ids>     Filter by category IDs
      --no-dynamic           Disable dynamic value modifiers

Introspection:
      --list-sections        List all available sections
      --list-presets         List weight presets with dimension weights
      --preview              Preview selection without rendering
      --explain              Show selection reasoning

Configuration:
      --primer-config <path> Custom primer config [default: .acp/primer.json]
      --cache <path>         Cache file for project state [default: .acp/acp.cache.json]

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)
acp primer -b 100

# Minimal tier primer (~400 tokens)
acp primer -b 350

# Standard tier primer (~600 tokens)
acp primer -b 500 --explain

# Full tier primer with MCP capability
acp primer -b 800 --capabilities mcp --preset safe

# Standalone mode for raw API usage
acp primer -b 500 --standalone

# List available sections
acp primer --list-sections

# Preview what would be selected
acp primer -b 400 --preview

# JSON output with tier metadata
acp primer --json

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).

acp context <OPERATION> [OPTIONS]

Operations:
  create <directory>    Get context for creating new files
  modify <file>         Get context for modifying existing files
  debug <target>        Get context for debugging (file or symbol)
  explore [--domain]    Get context for exploring the codebase

Options:
      --cache <path>    Cache file [default: .acp/acp.cache.json]
      --json            Output as JSON
      --verbose         Verbose output

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
acp context create src/auth/

# Get context before modifying a file
acp context modify src/auth/session.ts

# Get debug context for a symbol
acp context debug validateSession

# Explore the codebase structure
acp context explore

# Focus on a specific domain
acp context explore --domain auth

Configuration

Create .acp.config.json in your project root (or run acp init):

{
  "include": ["src/**/*", "lib/**/*"],
  "exclude": ["**/node_modules/**", "**/dist/**", "**/*.test.*"],
  "languages": ["typescript", "javascript", "rust", "python"],
  "output": {
    "cache": ".acp/acp.cache.json",
    "vars": ".acp/acp.vars.json"
  }
}

See the config schema for all options.

jq Quick Reference

Query the cache directly with jq:

# Check if you can modify a file
jq '.constraints.by_file["src/auth/session.ts"].mutation.level' .acp/acp.cache.json

# Get all frozen files
jq '.constraints.by_lock_level.frozen' .acp/acp.cache.json

# Find expired hacks
jq '.constraints.hacks | map(select(.expires < now | todate))' .acp/acp.cache.json

# Get symbol info
jq '.symbols["validateSession"]' .acp/acp.cache.json

# List all domains
jq '.domains | keys' .acp/acp.cache.json

# Get files in a domain
jq '.domains.auth.files' .acp/acp.cache.json

# Show codebase stats
jq '.stats' .acp/acp.cache.json

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:

acp install mcp

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
.cursorrules

# Bootstrap for Claude Code, Cline
CLAUDE.md

# Both include primers and project context

Using Primers with IDEs:

# IDE context (auto-detected) - no --standalone needed
acp primer -b 500

# Raw API usage (e.g., direct Anthropic API calls)
acp primer -b 500 --standalone

Environment Variables:

Variable	Purpose
`ACP_NO_IDE_DETECT=1`	Disable IDE detection

Example: Cursor Integration

# 1. Initialize project
acp init

# 2. Add primer to .cursorrules
echo "$(acp primer -b 400)" >> .cursorrules

# 3. Get context before modifications
acp context modify src/auth/session.ts

Example: Claude Code Integration

# 1. Initialize project
acp init

# 2. Add primer to CLAUDE.md
echo "$(acp primer -b 500)" >> CLAUDE.md

# 3. Use context command for operations
acp context create src/utils/
acp context debug validateSession

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.

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for vulnerability reporting.

License

MIT — see LICENSE

Commit count: 0

acp-protocol

documentation

README

ACP CLI

Installation

From crates.io (Recommended)

From Homebrew

From npm

Pre-built Binaries

Building from Source

Quick Start

1. Initialize Your Project

2. Index Your Codebase

3. Generate Annotations (Optional)

4. Generate Variables

5. Query the Cache

Commands

Global Options

acp init

acp install

acp index

acp annotate

acp review

acp vars

acp query

acp expand

acp chain

acp daemon

acp attempt

acp check

acp revert

acp watch

acp validate

acp primer

acp context

Configuration

jq Quick Reference

MCP Integration

IDE Integration

Key Annotations

Type Annotations (RFC-0008)

Related Documentation

Contributing

Security

License

cargo fmt

`acp init`

`acp install`

`acp index`

`acp annotate`

`acp review`

`acp vars`

`acp query`

`acp expand`

`acp chain`

`acp daemon`

`acp attempt`

`acp check`

`acp revert`

`acp watch`

`acp validate`

`acp primer`

`acp context`