<p align="center" <img src="acpxbanner.svg" alt="acpx banner" width="100%" / </p
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/setmode and session/setconfigoption
- Crash reconnect: dead agent processes are detected and sessions are resumed or reloaded automatically
- Prompt from file/stdin: --file <path or piped stdin for prompt content
- Config files: global + project JSON config with acpx config show|init
- Session inspect/history: sessions show and sessions history --limit <n
- Session export/import: move portable session archives between machines
- Local status checks: status reports running/idle/dead/no-session, pid, uptime, last prompt
- Client methods: stable fs/ and terminal/ handlers with permission controls and cwd sandboxing
- Capability opt-outs: let adapters use their native filesystem or terminal tools with --no-fs and --no-terminal
- Auth handshake: stable authenticate support via env/config credentials
- Structured output: typed ACP messages (thinking, tool calls, diffs) instead of ANSI scraping
- Any ACP agent: built-in registry + --agent escape hatch for custom servers
- One-shot mode: exec for stateless fire-and-forget tasks
- Compare across agents: acpx compare pi openclaw codex 'fix the bug' runs the same one-shot prompt against multiple ACP-compatible agents and summarizes timing, token usage, permissions, and final output side by side
- Experimental flows: flow run <file for TypeScript workflow modules over multiple prompts
- Runtime-owned flow actions: shell-backed action steps can prepare workspaces and other deterministic mechanics outside the agent turn
- Flow workspace isolation: acp nodes can target an explicit per-step cwd, so flows can keep agent work inside disposable worktrees
$ acpx codex sessions new
$ acpx codex "find the flaky test and fix it"
[thinking] Investigating test suite for flaky failures
[tool] Run npm test -- --reporter=verbose (running)
[tool] Run npm test -- --reporter=verbose (completed)
output:
✓ auth.login (0.8s)
✗ checkout.submit (timed out after 5000ms)
✓ cart.add (0.3s)
[tool] Edit src/checkout.test.ts (completed) output: Success. Updated 1 file.
[tool] Run npm test -- checkout.submit (completed) output: ✓ checkout.submit (0.4s)
Fixed: added await to the setup hook in checkout.submit. The test was reading stale state from the previous run.
[done] endturn
## Quick setup — tell your agent about acpx
Copy the block below and paste it into your Pi, OpenClaw, Claude Code, or similar agent harness. It will install acpx, read the skill reference, and know how to use ACP for all future coding agent tasks.