acpx — ACP CLI for Coding Agents

Main

• Prefer named sessions per goal (e.g., api, docs) so you can run parallel agent work without mixing histories.

• Use --file for long prompts: keep prompt context in version control and avoid copy/paste drift.

• Treat ~/.acpx/ as state: back it up or clear it when debugging session issues across projects.

• Start with the README “agent prerequisites” list to ensure the underlying agent (Codex/Claude) is installed and reachable.

README (excerpt)

acpx

⚠️ acpx is in alpha and the CLI/runtime interfaces are likely to change. Anything you build downstream of this might break until it stabilizes.

ACP coverage status: see ACP Spec Coverage Roadmap.

Your agents love acpx! 🤖❤️ They hate having to scrape characters from a PTY session 😤

acpx is a headless CLI client for the Agent Client Protocol (ACP), so AI agents and orchestrators can talk to coding agents over a structured protocol instead of PTY scraping.

One command surface for Pi, OpenClaw ACP, Codex, Claude, and other ACP-compatible agents. Built for agent-to-agent communication over the command line.

• Persistent sessions: multi-turn conversations that survive across invocations, scoped per repo
• Named sessions: run parallel workstreams in the same repo (-s backend, -s frontend)
• Prompt queueing: submit prompts while one is already running, they execute in order
• Cooperative cancel command: cancel sends ACP session/cancel via queue IPC without tearing down session state
• Soft-close lifecycle: close sessions without deleting history from disk
• Queue owner TTL: keep queue owners alive briefly for follow-up prompts (--ttl)
• Fire-and-forget: --no-wait queues a prompt and returns immediately
• Graceful cancel: Ctrl+C sends ACP session/cancel before force-kill fallback
• Session controls: set-mode and set <key> <value> for session/set_mode and session/set_config_option
• Crash reconnect: dead agent processes are detected and sessions are reloaded automatically

Source-backed notes

• README shows installs via npm install -g acpx@latest and usage via npx acpx@latest ....
• README documents session commands like acpx codex sessions new and acpx codex sessions list.
• README states session state lives under ~/.acpx/ and adapters can be auto-downloaded on first use.

FAQ

• Do I need a global install?: No—README shows npx acpx@latest for zero-install usage.
• Where does session state live?: README states it lives under ~/.acpx/ by default.
• Which agents are supported?: README lists adapters for Codex, Claude Code, and others via ACP.