acp-cli: Instructions file for Claude Code

acp-cli

Headless CLI client for the Agent Client Protocol (ACP). Rust port of ACPX.

Commands

cargo fmt                    # format
cargo clippy -- -D warnings  # lint
cargo test                   # test (needs LIBRARY_PATH on macOS, see below)
cargo check                  # fast compile check

macOS linker fix (libiconv):

LIBRARY_PATH="/opt/homebrew/opt/libiconv/lib" cargo test

Source Structure

src/
├── main.rs              # CLI entry point, clap parsing, command dispatch
├── lib.rs               # Public library API (re-exports)
├── config.rs            # AcpCliConfig — global + project config loading/merging
├── error.rs             # AcpCliError enum (thiserror)
├── agent/
│   └── registry.rs      # Agent name → command resolution (14 built-in agents)
├── bridge/
│   ├── mod.rs           # AcpBridge — spawn_blocking + LocalSet bridge to !Send ACP futures
│   ├── commands.rs      # BridgeCommand enum (Prompt, Cancel, SetMode, SetConfig, Shutdown)
│   └── events.rs        # BridgeEvent enum (TextChunk, ToolUse, PermissionRequest, etc.)
├── cli/
│   ├── mod.rs           # Cli struct (clap), Commands/SessionAction/ConfigAction enums
│   ├── init.rs          # `acp-cli init` interactive setup
│   ├── prompt.rs        # run_prompt() (persistent session) + run_exec() (one-shot)
│   ├── prompt_source.rs # Resolve prompt from args, file, or stdin
│   └── session.rs       # Session subcommands (new, list, show, close, history, cancel, status)
├── client/
│   ├── mod.rs           # BridgedAcpClient — ACP client handler (tool use, permissions)
│   └── permissions.rs   # PermissionMode (ApproveAll, ApproveReads, DenyAll)
├── output/
│   ├── mod.rs           # OutputRenderer trait
│   ├── text.rs          # TextRenderer (streaming + spinner)
│   ├── json.rs          # JsonRenderer (NDJSON events)
│   └── quiet.rs         # QuietRenderer (final text only)
├── queue/
│   ├── mod.rs           # Queue system overview
│   ├── owner.rs         # QueueOwner — holds agent connection, IPC server
│   ├── client.rs        # QueueClient — connects to owner via Unix socket
│   ├── ipc.rs           # IPC protocol (Unix socket)
│   ├── lease.rs         # Lease/heartbeat management
│   └── messages.rs      # IPC message types
└── session/
    ├── mod.rs
    ├── scoping.rs       # Session key: SHA-256(agent + dir + name), git root resolution
    ├── persistence.rs   # Session record JSON (create, load, update, close)
    ├── history.rs       # Conversation history (JSONL append)
    └── pid.rs           # PID file management