acpx — ACP CLI for Coding Agents

Main

• 按目标拆成命名会话（如 api/docs），让并行 agent 任务不互相污染上下文与历史。

• 长提示词用 --file 管理：把上下文放进版本库，避免复制粘贴造成漂移。

• 把 ~/.acpx/ 当作运行态状态：排障时可备份/清理，避免旧会话影响新项目。

• 先按 README 的 prerequisites 检查底层 agent（Codex/Claude）是否安装并可调用。

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 给出安装方式 npm install -g acpx@latest，也支持 npx acpx@latest ... 免安装运行。
• README 列出会话相关命令，如 acpx codex sessions new / sessions list 等。
• README 提到会话状态存放在 ~/.acpx/，并且首次使用可自动下载适配器。

FAQ

• 必须全局安装吗？：不必须：README 提供 npx acpx@latest 的免安装用法。
• 会话状态在哪里？：README 说明默认在 ~/.acpx/。
• 支持哪些 agent？：README 列出 Codex、Claude Code 等适配器，并通过 ACP 统一调用。