acpx gives agents, orchestrators, and developers one structured command-line interface to coding agents that speak the Agent Client Protocol (ACP), instead of driving each agent through its interactive terminal. The same command shape works across Pi, OpenClaw, Codex, Claude Code, and any custom ACP server, so a script can switch agents without changing how it sends prompts or reads results.
Persistent sessions are scoped to the current repository and keep context across invocations, with named sessions for parallel workstreams. Prompts submitted while a turn is running queue and drain in order, cancellation is cooperative, and dead agent processes are detected and reloaded. A separate stateless mode runs one-shot prompts with no saved context.
For automation, output can be human-readable text, NDJSON ACP events, or only the final assistant text. Tool calls, thinking, diffs, and completion state arrive as structured events rather than scraped terminal output. Permission policy is set per run, from approving reads only to approving or denying everything, and the working directory sets the session scope and filesystem guardrail (not an OS sandbox). TypeScript flows combine multiple ACP turns with deterministic actions, decisions, computation, and checkpoints, and the session runtime and flow engine are exported for applications that embed them. The project is pre-1.0, so its interfaces are still changing.
Features
- One interface for many agents: built-in adapters for Pi, OpenClaw, Codex, and Claude Code, plus any custom ACP server
- Persistent sessions: repository-scoped, multi-turn sessions that survive across invocations, with named parallel workstreams
- One-shot runs: stateless prompts with no saved session
- Queue-aware prompting: follow-up prompts queue behind a running turn, with fire-and-forget submission and cooperative cancel
- Crash recovery: dead agent processes are detected and reloaded automatically
- Structured output: text, NDJSON event, and quiet modes, with tool calls, thinking, and diffs as structured events
- Permission policy: approve reads (default), approve all, or deny all, plus a working-directory guardrail
- Flows: TypeScript workflows mixing ACP turns with action, compute, decision, and checkpoint steps, with persisted run state
- Embeddable runtime: exported runtime and flow modules, including a shared session owner for apps and CLI processes
- Agent comparison: runs one prompt across multiple agents
