Technology RadarTechnology Radar

acpx

agentopen-sourcemulti-agent
Assess

acpx is a headless CLI client for Agent Client Protocol (ACP) sessions — "curl for coding agents." It lets orchestrators drive Pi, Claude Code, Codex, Gemini CLI, and any other ACP-compatible agent through structured protocol messages instead of PTY scraping.

What It Is

The classic problem with multi-agent coding pipelines is that agents weren't designed to be driven by other agents — they're designed for humans at a terminal. Without a structured interface, orchestrators resort to parsing ANSI-escaped terminal output, which is brittle and fragile.

acpx solves this by speaking the ACP (JSON-RPC 2.0 over stdio) protocol directly against any registered coding agent. You get:

  • Persistent sessions — multi-turn conversations scoped per-repository that survive process restarts
  • Named sessions — run acpx -s backend and acpx -s frontend in the same repo simultaneously
  • Prompt queueing — submit multiple prompts sequentially without race conditions
  • Structured output — typed ACP messages (thinking, tool calls, diffs) instead of ANSI parsing
  • Crash recovery — dead agent processes are detected; sessions reload automatically
  • Flow Runtime (v0.4+) — TypeScript workflow modules for node-based multi-step orchestration
  • System prompt injection (v0.6.0) — --system-prompt and --append-system-prompt global flags forward through ACP _meta.systemPrompt on session creation; useful for injecting context or constraints at orchestration time

The ACP Context

This entry is about driving coding agents headlessly over ACP — not to be confused with the IBM/BeeAI "Agent Communication Protocol" (also abbreviated ACP, see that entry, which is in Hold). The Zed/JetBrains ACP this tool uses is a different, active protocol. See the Agent Client Protocol entry for background on the protocol itself.

Supported Agents

Built-in adapters cover the major coding agents:

Agent Notes
Claude Code Via claude-agent-acp adapter
Gemini CLI Reference ACP implementation
GitHub Copilot CLI GA since Feb 2026
OpenAI Codex Via adapter
Pi Native (same org as acpx)
Kimi CLI Native ACP
Goose Native ACP
Cursor, Kilocode, Factory Droid, iFlow Also supported

Custom agent servers are supported via an escape hatch for agents not in the built-in registry.

Flow Runtime: Agentic Graphs

v0.4 introduced "Agentic Graphs" — TypeScript workflow modules where you define node-based pipelines to drive any ACP agent through deterministic steps. This is the primary reason to watch acpx: it turns the "drive an agent from a script" pattern from a one-off hack into a repeatable architecture. Use cases include CI/CD pipelines that run an agent against a failing test, multi-agent review workflows, and automated refactoring across parallel sessions.

Limitations

  • Alpha status — CLI interfaces are unstable; the project explicitly warns they may change
  • Session resume gap — on reconnect, ACP history is not replayed; the IDE/orchestrator must handle missing prior context
  • ACP is pre-1.0 (v0.11.3 as of March 2026) — acpx inherits the protocol's instability
  • Node.js 22.12.0+ required — newer than many CI environments default to
  • Created by OpenClaw org — same supply chain and governance concerns as OpenClaw itself; audit before adding to CI. v0.6.0 tightened IPC socket permissions to owner-only and uses cryptographically random owner generation IDs — a material improvement, but governance fundamentals unchanged

Why Assess (Not Trial)

acpx solves a real problem — there's no good prior art for headlessly orchestrating ACP agents — and the Flow Runtime is a genuinely useful abstraction. But both the tool and the protocol it depends on are in early, unstable states. The session resume gap is a real correctness issue for stateful workflows. Wait for:

  1. ACP v1.0 and stable acpx CLI contracts
  2. Session history replay on reconnect
  3. The OpenClaw foundation governance to be operational (reduces supply-chain risk)

Quick Start

npm install -g acpx@latest
# Start a session and send a prompt to Claude Code
acpx --agent claude-code prompt "Add error handling to src/index.ts"
# Named parallel sessions
acpx -s backend --agent claude-code prompt "Write tests for the API layer"
acpx -s frontend --agent gemini-cli prompt "Review the React component"
# Inject a system prompt at orchestration time (v0.6.0+)
acpx --agent claude-code --system-prompt "You are a security reviewer. Focus only on OWASP Top 10." \
  prompt "Review src/auth.ts"

Key Characteristics

Property Value
Created by openclaw org (same as OpenClaw)
License MIT
Language TypeScript (95%)
GitHub stars ~2,500 (April 2026)
Latest release v0.6.0 (April 2026)
Status Alpha (CLI interfaces may change)
Protocol ACP v0.11.3 (JSON-RPC 2.0 over stdio)
Install npm install -g acpx@latest
GitHub openclaw/acpx

Sources