acpx is a headless command-line client for the Agent Client Protocol. It gives orchestrators, scripts, and people one structured interface to coding agents — persistent sessions, one-shot runs, permission policy, and machine-readable output — instead of scraping a terminal UI.
Sessions are created explicitly and scoped to the current repository, so context survives across invocations and automation never starts an unexpected conversation by accident. Named sessions run parallel workstreams, follow-up prompts queue while a turn is in flight, and cancel sends an ACP session/cancel before any force-kill. Dead agent processes are detected and reloaded. Session state lives under ~/.acpx/. Use exec for a stateless run with no saved session.
Output has three modes: human-readable text, NDJSON ACP events under --format json for automation, and --format quiet for the final assistant text alone. Thinking, tool calls, diffs, and completion state come through as structured events rather than ANSI escape sequences. Permission policy is a flag — approve-all, approve-reads, or deny-all — and --cwd sets both the session scope and the filesystem boundary; global and project JSON configuration supply defaults that flags override.
For multi-step work, acpx flow run executes a TypeScript workflow combining ACP turns with deterministic action, compute, decision, and checkpoint nodes, with run state persisted for replay. The package also exports acpx/runtime and acpx/flows so applications can embed session storage, queue ownership, and ACP wire handling without shelling out. The project describes itself as pre-1.0, with the CLI and runtime interfaces evolving.
| Agent | Command |
|---|---|
| Codex | acpx codex … |
| Claude Code | acpx claude … |
| Gemini CLI | acpx gemini … |
| OpenClaw | acpx openclaw … |
| Custom ACP server | acpx --agent ' ' … |
Features
- One surface for many agents: built-in launch profiles plus --agent for any custom ACP server
- Persistent sessions: repository-scoped multi-turn context, with -s for parallel workstreams
- Queue-aware prompts: prompts submitted mid-turn queue and drain in order; --no-wait enqueues and returns
- Crash resistance: dead agent processes are detected and reloaded, and cancellation is cooperative
- Structured output: text, json NDJSON events, and quiet modes, with stdout kept parseable
- Permission policy as a flag: --approve-all, --approve-reads, or --deny-all, scoped by --cwd
- Flows: TypeScript workflows over ACP turns plus action, compute, decision, and checkpoint nodes, with replay
- Embeddable: acpx/runtime and acpx/flows are public exports for higher-level tools
- Agent comparison: one prompt run across multiple agents for side-by-side output
Integrates with
Claude Code
Terminal-based agentic coding tool that reads your codebase and runs tasks through natural-language commands
Codex
Lightweight coding agent that runs in your terminal
OpenClaw
Self-hosted single-operator assistant runtime that links models, tools, and messaging channels through one local Gateway
Pi
Minimal, self-extensible terminal coding agent and harness with a multi-provider LLM API
