acpx

acpx is a headless CLI client for the Agent Client Protocol (ACP) that replaces traditional PTY terminal text scraping, enabling AI orchestrators to communicate with coding agents via structured protocol messages (thinking, tool calls, diffs).

Core Capabilities

• Multi-Agent Unified Interface: A single command surface adapting to ACP-compatible agents including Pi, OpenClaw ACP, Codex, and Claude, with auto-download of adapters via npx on first use
• Persistent Sessions: Multi-turn conversations spanning invocations, stored per-repo scope in ~/.acpx/, with named sessions for parallel workflows (e.g., -s backend, -s frontend)
• Prompt Queue & Cooperative Cancellation: Queued prompts execute in order when agent is busy; cancel sends ACP session/cancel via queue IPC without corrupting session state
• Fine-Grained Permission Policies: --approve-all, --approve-reads, --deny-all, --non-interactive-permissions fail
• Multiple Output Formats: text (human-readable), json (NDJSON for automation), quiet (final output only), --suppress-reads
• Fire-and-Forget & Stateless Execution: --no-wait queues and returns immediately; exec for one-shot stateless execution
• Soft-Close & Crash Reconnection: Close sessions preserving disk history; auto-detect dead agent processes and reload sessions

Experimental Flows System TypeScript workflow modules supporting acp / action / compute / checkpoint step types for multi-step ACP task orchestration, with an in-browser replay viewer (React 19 + @xyflow/react + Vite).

Configuration Global ~/.acpx/config.json → project-level <cwd>/.acpxrc.json → CLI flags, increasing priority. Auth handshake via config auth field or ACPX_AUTH_<METHOD_ID> env vars. Custom agent registration via config agents field.

Programmatic Embedding acpx/runtime export for programmatic integration in Node.js applications. Includes a data-driven ACP Core v1 conformance test suite.

Use Cases

• Agent-to-Agent communication: orchestrators programmatically invoke coding agents for structured output
• Parallel code review/fixes: named sessions execute different tasks on the same repo concurrently
• CI/CD integration: headless execution via exec mode + NDJSON output in pipelines
• Multi-step workflow automation: Flows orchestrate complex multi-round coding flows (e.g., PR triage)

Prerequisites: Node.js ≥ 22.12.0. Currently in Alpha stage (v0.6.1), CLI/runtime interfaces may change.

Note: The formal definition source of the ACP specification (openclaw-originated or external standard) is not explicitly stated in the repo; npm publication status is unverified; OpenClaw organization background information is limited.