claude-code-cli-acp

ACP adapter for the real interactive Claude Code CLI.

The adapter runs claude through a PTY, reads Claude transcript JSONL for canonical content, and exposes an Agent Client Protocol server for editors. It also keeps a direct interactive pass-through mode and a print mode that replaces claude -p by using the interactive CLI path.

Install

Prerequisites:

• Install and authenticate Claude Code: npm install -g @anthropic-ai/claude-code, then run claude.
• Use Node 18+ for the npm wrapper.
• Use Rust 1.95+ when building from source.

Recommended install after npm publication:

npm install -g claude-code-cli-acp
claude-code-cli-acp doctor

Other supported install paths:

cargo install claude-code-cli-acp --locked
cargo install --git https://github.com/moabualruz/claude-code-cli-acp --locked
cargo install --path . --locked

Direct GitHub release archives and future Homebrew tap setup are documented in docs/install.md.

ACP Setup

Configure any ACP-compatible client to run:

claude-code-cli-acp

The ACP server speaks JSON-RPC over stdio. Editor clients must launch it as a local agent process, not through a shell that writes prompts or banners to stdout.

Zed setup details live in docs/editor-setup.md.

Zed supports registry-installed external agents and manual custom agents. This adapter can be used manually today through Zed agent_servers, and the ACP Registry publishing checklist is documented in docs/publishing.md.

CLI Modes

Interactive pass-through:

claude-code-cli-acp interactive -- --model sonnet

Default no-handshake invocation behaves like interactive pass-through, but do not alias over claude; that name belongs to the installed Claude Code CLI. If you want a shortcut, use a non-conflicting name:

alias claude-acp='claude-code-cli-acp'

Print mode drives interactive Claude and extracts transcript output. It must not call claude -p for core behavior:

claude-code-cli-acp print "summarize this repo"
echo "write release notes" | claude-code-cli-acp print --output-format json

Doctor and drift checks:

claude-code-cli-acp doctor
claude-code-cli-acp doctor --live-docs
just drift-live

doctor --live-docs compares local claude --help, installed version, npm metadata, and official docs assumptions against the compatibility matrix.

Verification

Local gate:

just ci

Real e2e is opt-in because it uses the installed Claude CLI and can create transcript records under ~/.claude:

just real-e2e

See docs/real-e2e.md for prerequisites and expected coverage.

Developer and package validation docs live in docs/development.md. Publishing workflow docs live in docs/publishing.md.

Security

Claude transcripts are plaintext under ~/.claude/projects/<project>/<session>.jsonl. This adapter treats transcript text as sensitive: no body text in logs by default, redaction in diagnostics, and explicit unsafe opt-in required for full transcript debugging.

More detail: docs/security.md.

Compatibility

Claude Code changes quickly. Compatibility rules and drift procedure live in docs/compatibility.md.

Attribution

This project was inspired and guided by Zed codex-acp, agentclientprotocol/claude-agent-acp, OpenAI Codex, OpenCode, and the ACP/Rust SDK ecosystem. Packaging templates use the public Simple Icons Claude SVG. See NOTICE.md.

License

Apache-2.0.