acpx
One headless CLI to drive stateful Agent Client Protocol sessions across ACP-compatible coding agents.
- Source repo
- openclaw/acpx
- Stars
- ★ 3.4k
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 57/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer wants Codex or Claude Code to keep context across several invocations in one repo and run parallel named workstreams.
- Not a fit if
- Users who want a chat UI instead of a terminal workflow
- Teams needing a stable API while acpx is pre-1.0
- Anyone whose coding agent has no ACP-compatible adapter
- Source review
- 57/100 · Major gaps
What does this agent do, and when should you use it?
acpx is a headless command-line client for the Agent Client Protocol (ACP), published on npm under the MIT license by openclaw. It puts Codex, Claude Code, Pi, OpenClaw and custom ACP servers behind one command shape, so switching agents is a one-word change. It supports persistent named sessions kept under ~/.acpx/, stateless exec runs, and three output modes: plain text, NDJSON events via --format json, and final-text-only via --format quiet. Sessions are scoped to the current repository and persist across invocations, with queueing, cancellation, export/import and reconnect handling. It also ships permission modes, a --cwd filesystem boundary, global and project JSON configuration, and TypeScript multi-step workflows through acpx flow run. Beyond the CLI, the package exports acpx/runtime and acpx/flows, and createSharedAcpRuntime() lets an application and CLI processes share one local session owner. The project is pre-1.0, so CLI and runtime interfaces are explicitly still evolving.
acpx takes a subcommand plus an agent name (for example acpx codex …), launches the matching ACP-compatible agent process and speaks the ACP protocol with it. It reads the prompt from arguments or stdin, the working directory from --cwd, global and project JSON configuration, and command-line flags (flags win), then creates, names, reuses or switches sessions stored under ~/.acpx/; follow-up prompts are queued while a turn is running. The output layer renders ACP events as terminal text, as NDJSON with --format json (retaining structured thinking, tool calls, diffs and completion state), or prints only the final assistant text with --format quiet. acpx flow run executes TypeScript workflows that combine ACP turns with deterministic actions, decisions, computation and checkpoints, while acpx/runtime and acpx/flows expose those primitives to code callers.
- A developer wants Codex or Claude Code to keep context across several invocations in one repo and run parallel named workstreams.
- A CI job or automation script needs machine-readable output and parses tool calls and completion state from NDJSON events.
- A team wants to run one prompt across several ACP-compatible agents for comparison.
- Someone needs tight filesystem boundaries and permission policies (from read approval to deny-all or approve-all) before letting an agent edit code.
- An application developer wants to embed session and workflow primitives without shelling out to the CLI.
- An engineering team needs to chain agent turns with deterministic computation, conditional decisions and checkpoints in TypeScript.
How do you install or deploy this agent?
acpx requires Node.js 22.13 or newer, plus the coding agent you intend to use, installed and authenticated (where its adapter does not handle that). Install the package globally:
npm install -g acpx@latestTo try it without a global install, use npx:
npx acpx@latest --helpBuilding from source uses pnpm:
pnpm install --frozen-lockfile
pnpm run checkHow do you use this agent?
Create a session explicitly in your repository, then send a prompt:
acpx codex sessions new
acpx codex "find the slowest test and explain why"Use named sessions and stateless one-shot runs:
acpx codex sessions new --name backend
acpx codex -s backend "trace the checkout timeout"
acpx codex exec "summarize this repository"Switch agents, target a custom ACP server, or set model options:
acpx claude exec "review this diff"
acpx --agent '<command>' exec "hello"
acpx --model gpt-5.4 codex exec --config-option reasoning_effort=high "review this repository"Emit NDJSON for automation and constrain the working directory:
acpx --cwd /path/to/repo --format json codex exec "list failing tests"What are this agent's strengths and limitations?
- One command shape spans Codex, Claude Code, Pi, OpenClaw and custom ACP servers, so changing agents is a single argument.
- Persistent named sessions keep context across invocations and support parallel workstreams plus queued prompts during a running turn.
- --format json emits NDJSON ACP events that retain tool calls, diffs and completion state for automation.
- Ships as a CLI plus acpx/runtime, acpx/flows and createSharedAcpRuntime() for embedding in applications.
- Permission modes and the --cwd filesystem boundary make session scope and write access explicit.
- The project is pre-1.0 and the README says CLI and runtime interfaces will change, so upgrades carry breakage risk.
- It supplies no model or agent capability itself; without a separately installed and authenticated upstream coding agent there is nothing to drive.
- Requires Node.js 22.13 or newer, forcing an upgrade on older runtimes.
- Session state lives under ~/.acpx/, so queue ownership and reconnects across processes or machines must be managed per the docs.
- Workflow support is limited to TypeScript flows, which may need extra adaptation for non-TypeScript stacks.
How does this agent compare with similar options?
The README names no specific competitor; it positions acpx as a replacement for driving coding agents by hand in an interactive terminal, offering a structured ACP client instead.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| acpx This agent | 57 · Major gaps | CLIFree + model costs | ★ 3.4k | today | TypeScript | Codex · Claude Code |
| MonoCode | 56 · Major gaps | Desktop appFree | ★ 3.2k | today | TypeScript | Codex · Claude Code |
| Mirafold | 89 · Good | CLIFreemium | ★ 18 | 1mo ago | TypeScript | Codex · Claude Code |
| Atlas | 50 · Major gaps | Desktop appFree + model costs | ★ 9.6k | 1d ago | Rust | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Permission model is well documented: default approve-reads, mutually exclusive --deny-all/--approve-all, non-interactive deny default, fs-safe root with symlink/hardlink guards, --no-fs/--no-terminal capability switches, and an explicit disclaimer that this is not an OS sandbox (least_privilege 2). Per-request interactive confirmation and a flow explicit-grant design exist (user_confirmation 2). Data storage locations are transparently tabulated in install.md (data_flow_transparency 2). Sensitive data handling shows 0600/0700 perms, auth env/config separation, and SECURITY.md guidance (sensitive_data_handling 2). Dependency security shows only CI and lockfile references; no audit/SBOM/vuln policy, and built-in adapters are auto-fetched via npx with partial version ranges (dependency_security 1). External effects: docs admit cancellation does not undo completed writes or command effects, no rollback (external_effects 1). Rollback limited to session prune/export-import and flow run bundles, no operation-level rollback (rollback 1). Source attribution has MIT and author field, but publisher is unverified with no signing/provenance (source_attribution 1).
Docs, code, and tests agree on agent registry, permission modes, and exit codes (self_consistency 2). Dependency availability relies on Node 22.13+, pnpm 11.26, uvx, upstream CLIs, and npx first-fetch, i.e. external prerequisites (dependency_availability 1). Failure messages include exit code 5, PERMISSION_PROMPT_UNAVAILABLE, and preflight failure text (failure_messages 2).
Targets developers, orchestrators, and embedding hosts across sessions/one-shot/flows/embedding (audience_and_scenarios 2). Capability boundaries clearly state non-sandbox and that --no-terminal does not stop adapter-native tools (capability_boundaries 2). Trigger precision via explicit session creation, permission policy precedence, non-interactive policy (trigger_precision 2). Environment fit covers Windows named pipes, argv migration, Node version matrix (environment_fit 2).
Documentation is well structured with README and layered docs (information_architecture 2). Install notes cover global/npx/source build and version requirements (install_notes 2). Naming stability is explicitly warned as pre-1.0 with evolving CLI/runtime surface (naming_stability 1). Examples and quickstart are thorough (examples_and_faq 2). Known limitations are honestly disclosed in permissions/SECURITY (known_limitations 2). MIT license is complete (license 2). Version 0.20.0 exists but CHANGELOG is only linked, not in evidence (versioning_changelog 1). Maintenance responsibility points to OpenClaw Team and SECURITY contact, but publisher is unverified (maintenance_responsibility 1).
Output formats text/json/json-strict/quiet with structured events aid automation (output_usability 2). Clear marginal value over raw PTY scraping via structured ACP sessions (marginal_value 2). Cost is Node runtime and npx first-fetch overhead, which docs note (cost_benefit 2).
Most README claims trace to docs and test files, but some behaviors (flow permission enforcement) are self-described as design targets rather than implemented (claim_traceability 1). Cross-source corroboration is limited to README/docs/tests/CI with no independent third party (cross_source_corroboration 1). Docs clearly separate design targets from implemented state, so fact/inference separation is good (fact_inference_separation 2).
- Publisher identity is unverified; attribution and maintenance responsibility rest on repository metadata alone and must not be read as reliability or safety evidence.
- Built-in adapters are auto-fetched via npx with caret version ranges, executing external packages on first run — a supply-chain risk; pin versions and audit.
- Docs explicitly state acpx is not an OS sandbox; --no-terminal/--no-fs do not stop adapter-native tools or child processes, and cancellation does not undo completed writes or commands.
- The flow permission enforcement model is self-described as a design target and may not be fully implemented; do not assume it is enforced.
- Pre-1.0: CLI and runtime interfaces may break between minor versions.