ACPX is a headless command-line client for the Agent Client Protocol (ACP) that enables AI agents and orchestrators to communicate with coding agents through a structured protocol rather than terminal scraping. Written in TypeScript and available at acpx.sh, the tool provides a unified command surface for multiple ACP-compatible agents including Pi, OpenClaw, Codex, Claude, Gemini, Cursor, GitHub Copilot, and many others. The project is currently in alpha with interfaces subject to change.
The repository implements persistent, stateful ACP sessions that survive across command invocations and are scoped per repository. Sessions can be named to run parallel workstreams in the same codebase, such as separate backend and frontend sessions. The tool supports prompt queueing, allowing users to submit prompts while one is already executing, with queued prompts executing in order. A cooperative cancel command sends ACP session cancellation via inter-process communication without destroying session state, and graceful cancellation via Ctrl+C sends the ACP cancel request before falling back to force-kill.
Key features include soft-close lifecycle management that closes sessions without deleting history, queue owner time-to-live configuration to keep queue owners alive for follow-up prompts, and fire-and-forget mode with the no-wait flag that queues prompts and returns immediately. The tool handles crash recovery by detecting dead agent processes and automatically resuming or reloading sessions. Session controls support set-mode and configuration option setting through ACP protocol methods. Users can inspect session status, view history with configurable limits, and export or import portable session archives between machines.
ACPX provides structured output of ACP messages including thinking, tool calls, and diffs instead of ANSI scraping. It includes stable client method handlers for filesystem and terminal operations with permission controls and current working directory sandboxing. Authentication handshake support is available through environment variables or configuration credentials. The tool supports one-shot stateless execution mode and includes a compare feature that runs the same prompt against multiple ACP-compatible agents, summarizing timing, token usage, permissions, and output side by side.
The repository includes experimental flow support through TypeScript workflow modules that execute over multiple prompts. Flow workspace isolation allows ACP nodes to target explicit per-step working directories, keeping agent work inside disposable worktrees. Runtime-owned flow actions enable shell-backed action steps for workspace preparation and deterministic mechanics outside agent turns.
Configuration is handled through global and project-level JSON files, with CLI flags taking precedence. The tool supports MCP server configuration and multiple output formats including human-readable text, raw ACP NDJSON for automation, and quiet mode. Session control payloads include stable envelopes with acpxRecordId and acpxSessionId for correlation.
GitGenius activity data shows the repository has 77 tracked issues and pull requests with a median response latency of 37.5 hours and mean latency of 172.2 hours. The most active labels are P2 priority items, clawsweeper needs-maintainer-review, and clawsweeper needs-product-decision tags. Primary contributors tracked include steipete with 68 events, vincentkoc with 39 events, and oldjs with 8 events. The repository overlaps with openclaw/openclaw, yeachan-heo/oh-my-claudecode, and meteor/meteor through shared contributors.
