acpx — Summary

Slug: acpx Repo: openclaw/acpx Stars: 2759 | Forks: 271 License: MIT Language: TypeScript (Node.js ≥ 22.13.0) Package: npm install -g acpx Homepage: https://acpx.sh

One-Line Description

Headless CLI client for stateful Agent Client Protocol (ACP) sessions — enables agent-to-agent communication without PTY scraping.

What It Is

acpx is a TypeScript/Node.js CLI that wraps the Agent Client Protocol (ACP) to let AI agents, orchestrators, and harnesses talk to coding agents (Claude Code, Codex, Pi, Cursor, Copilot, Gemini, Kiro, and 10+ others) over a structured protocol. It is explicitly designed as an agent-first tool: the primary user is another agent or orchestrator, not a human.

Core Value Proposition

Before acpx: orchestrators had to spawn a PTY (pseudo-terminal), scrape ANSI escape codes, parse unstructured text output, and hope the agent's terminal session didn't die mid-task. After acpx: one CLI that speaks ACP, manages persistent multi-turn sessions, queues prompts safely, handles lifecycle (crash reconnect, cooperative cancel), and returns structured typed output (thinking, tool calls, diffs) — for 17 coding agents.

Key Primitives

• Persistent sessions: multi-turn conversations scoped per repo/cwd, survive across invocations
• Named sessions: run parallel workstreams in the same repo (-s backend, -s frontend)
• Prompt queueing: submit while a turn is in-flight; executes in order
• fire-and-forget: --no-wait queues without waiting
• exec mode: one-shot stateless execution (acpx codex exec "summarize repo")
• Flows: acpx flow run <file> — TypeScript workflow modules over multiple ACP turns, with acp/action/compute/checkpoint node types and decision/decisionEdge for branching
• Permission policy: approve-all, approve-reads, deny-all modes; JSON policy with autoApprove/autoDeny/escalate/defaultAction
• Structured output: text, json, quiet formats; --suppress-reads to hide file body dumps
• 17 built-in agents: pi, openclaw, codex, claude, gemini, cursor, copilot, droid, iflow, kilocode, kimi, kiro, opencode, qoder, qwen, trae + raw --agent escape hatch

Status

Alpha. API/CLI interfaces subject to change. ACP spec coverage tracked in docs/2026-02-19-acp-coverage-roadmap.md. Session state in ~/.acpx/.

acpx — Overview

Origin

Published as acpx on npm by openclaw. TypeScript/Node.js. MIT license. 2759 stars, 271 forks. Homepage: https://acpx.sh. In alpha; API subject to change.

Philosophy

"Your agents love acpx. They hate having to scrape characters from a PTY session."

acpx's thesis: the status quo for agent-to-agent communication is PTY scraping — spawning a terminal session and parsing ANSI escape codes to figure out what the agent said. This is fragile, unstructured, and breaks across agent versions. The Agent Client Protocol (ACP) solves this with a structured protocol; acpx is the reference headless CLI client for ACP.

From VISION.md:

"acpx should be the smallest useful ACP client: a lightweight CLI that lets one agent talk to another agent through the Agent Client Protocol without PTY scraping or adapter-specific glue." "The goal is not to build a giant orchestration layer. The goal is to make ACP practical, robust, and easy to compose in real workflows."

Design Goals

1. Interoperability first: maximize compatibility across ACP adapters and agent harnesses
2. Keep the core small: stay focused on ACP client concerns; avoid feature bloat
3. Robust by default: session continuity, safe queueing, clear failure modes, machine-readable output
4. Conventions are API surface: data models, config keys, output shapes, naming — all scrutinized before adding; convenience alone is not enough

What ACP Is

The Agent Client Protocol (ACP) is a structured JSON protocol for agent-to-agent communication over stdio/IPC. It replaces PTY scraping with typed messages: session/start, session/cancel, session/set_mode, session/set_config_option, permission requests (tool/request_permission), and structured responses (thinking, tool calls, diffs). acpx wraps this protocol in a human/machine-usable CLI.

Agent Registry

acpx ships with 17 built-in agent adapters:

Any unlisted agent is passed through as a raw command via --agent '<command>'.

Target Users

acpx is explicitly designed for agent-to-agent use: the primary user is an orchestrator, CI pipeline, or another AI agent. Humans can drive it directly, but human usability is a secondary constraint. The README includes an "install acpx in your agent" paste block specifically so an agent can set itself up to use acpx for all future coding-agent delegation.

acpx — Architecture

Distribution

npm: npm install -g acpx Runtime: Node.js ≥ 22.13.0 Package manager: pnpm 10.33.2 (for development) Binary: acpx

Source Structure

src/
├── cli.ts                    # Entry point
├── cli-core.ts               # Core CLI logic
├── cli-public.ts             # Public CLI surface
├── cli/                      # CLI command implementations
├── acp/                      # ACP protocol layer
├── agent-registry.ts         # Built-in agent → command mappings
├── async-control.ts          # Queue and async management
├── errors.ts                 # Error types
├── filesystem.ts             # Stable fs/* client methods
├── flows.ts                  # Flow orchestration
├── flows/                    # Flow authoring API
│   ├── authoring.ts          # defineFlow, decision, decisionEdge, acp, action, compute, checkpoint
│   ├── cli.ts                # flow run CLI command
│   ├── decision.ts           # decision/decisionEdge branching
│   ├── definition.ts         # flow definition types
│   ├── executors/            # step type executors
│   ├── graph.ts              # DAG graph
│   ├── runtime.ts            # flow runtime
│   └── store.ts              # run state persistence
├── mcp-servers.ts            # MCP server integration
├── perf-metrics.ts           # Performance metrics capture
├── permission-policy.ts      # JSON permission policy parsing
├── permission-prompt.ts      # Interactive permission prompts
├── permissions.ts            # Permission engine
├── persisted-key-policy.ts   # Persistent allow/deny decisions
├── process-liveness.ts       # Agent process health checks
├── prompt-content.ts         # Prompt input handling (text/file/stdin)
├── runtime.ts                # Main runtime
├── runtime/                  # Runtime components
├── session/                  # Session management
│   ├── persistence/          # Session storage
│   │   ├── repository.ts     # Session CRUD, pruning, git-root discovery
│   │   ├── serialize.ts      # Disk serialization
│   │   └── parse.ts          # Disk deserialization
│   ├── session.ts            # Session state machine
│   ├── event-log.ts          # Event log for session history
│   ├── export.ts             # Session export to archive
│   ├── import.ts             # Session import from archive
│   └── ...
├── spawn-command-options.ts  # Agent process spawn options
├── types.ts                  # Core type definitions
└── version.ts                # Version constants

Session Storage

Session state is stored under ~/.acpx/. Sessions are scoped to a git repository root (discovered via findGitRepositoryRoot) or the cwd if no git root is found.

~/.acpx/
├── config.json               # Global config
└── sessions/
    └── <agent>/
        └── <repo-hash>/
            ├── default/      # Default session for this repo
            │   ├── session.json
            │   └── history/
            └── <name>/       # Named session (-s <name>)
                ├── session.json
                └── history/

IPC for Prompt Queueing

When a session is already running (agent turn in progress), acpx uses IPC (Unix socket / named pipe) to queue the new prompt. The queue owner process receives it and executes it after the current turn completes. --no-wait enqueues and returns immediately (exit 0) without waiting for completion.

Flow Run Storage

~/.acpx/flows/runs/
└── <run-id>/
    ├── state.json            # Current run state
    └── checkpoints/          # Checkpoint snapshots

Permission Model

Three permission modes (set via CLI flag or config):

JSON policy --policy '<json>' provides fine-grained control:

{
  "autoApprove": ["fs/read*", "terminal/run_command:npm test"],
  "autoDeny": ["fs/delete*"],
  "escalate": ["terminal/run_command"],
  "defaultAction": "deny"
}

Output Formats

--suppress-reads hides file body content in tool outputs while still showing the tool call itself.

Exit Codes

These stable exit codes allow orchestrators to branch on failure types.

acpx — Components

CLI Command Surface

acpx [global_options] [agent] [verb] [options] [prompt_text...]

Verbs:

Session subcommands:

Global Options

Flows API

TypeScript flow authoring via acpx/flows:

Flow runs persist under ~/.acpx/flows/runs/. Flow inputs via --input-json or --input-file.

Skills Integration

skills/
└── acpx/
    └── SKILL.md    # Self-describing SKILL.md for agent consumption

The skill SKILL.md describes every command, flag, and workflow pattern. It is the primary reference for agents consuming acpx. Installation:

npx acpx --skill install acpx --agent codex --scope user
npx acpx --skill install acpx --agent claude --scope user

.agents/ Directory

agents/
├── README.md        # Lists all 17 built-in agents with commands
├── Claude.md        # Claude-specific notes
├── Codex.md         # Codex-specific notes
├── Copilot.md       # Copilot-specific notes
├── Cursor.md        # Cursor-specific notes
├── Droid.md         # Droid-specific notes (factory-droid alias)
├── Gemini.md        # Gemini-specific notes
├── Iflow.md         # iFlow-specific notes
├── Kilocode.md      # Kilocode-specific notes
├── Kimi.md          # Kimi-specific notes
├── Kiro.md          # Kiro-specific notes
├── OpenCode.md      # OpenCode-specific notes
├── Qoder.md         # Qoder-specific notes
├── Qwen.md          # Qwen-specific notes
└── Trae.md          # Trae-specific notes

Config Files

Two-level config merge (later wins):

CLI flags always win over config values. acpx config show shows the resolved merge. acpx config init creates a ~/.acpx/config.json template.

conformance/ Directory

conformance/          # ACP spec conformance tests

Tests that validate acpx against the ACP specification. Coverage tracked in docs/2026-02-19-acp-coverage-roadmap.md.

examples/flows/ Directory

examples/flows/
├── README.md
├── echo/             # Minimal echo flow
├── branch/           # Branching example
├── shell/            # Shell action example
├── workdir/          # Working directory isolation
├── two-turn/         # Multi-turn example
├── pr-triage/        # PR triage (acp → GitHub → acp)
└── replay-viewer/    # Browser-based run inspector

acpx — Uniqueness

Differentiator

acpx is the only framework in this corpus whose explicit, primary design goal is to be used by another agent — not by a human. It is an ACP protocol client first, a human CLI second. No other framework positions the agent-as-user this prominently or designs its API surface around it this consistently.

Differs from Seeds

Against the five seed archetypes and 11 seed frameworks:

vs. Skills-only behavioral (superpowers, spec-kit): Seeds add skills to help a single agent do more. acpx enables an agent to delegate to a completely different coding agent (Codex, Claude Code, Cursor, etc.) via a structured protocol. The orchestration is horizontal (agent → different agent), not vertical (agent → more capable self).

vs. Mirror commands+skills (claude-conductor, claude-flow, openspec): claude-conductor and claude-flow coordinate multiple Claude Code instances. acpx is protocol-level — it works with 17 different agents across 8 different vendors (OpenAI, Anthropic, GitHub, Google, etc.) and any agent that speaks ACP. It is not Claude-specific.

vs. MCP-anchored toolserver (spec-driver, ccmemory): Seeds add tools (MCP servers) to an agent. acpx wraps entire agents as addressable services. The level of abstraction is one layer higher: instead of adding a tool, you add an agent.

vs. Markdown scaffold (BMAD-METHOD, taskmaster-ai, agent-os, kiro): These define behavior through markdown files. acpx defines behavior through TypeScript flow modules and session state. The execution model is runtime (ACP protocol messages) not configuration (markdown instructions).

vs. Closed IDE with proprietary primitives (kiro): acpx explicitly supports Kiro as one of 17 agents (kiro -> kiro-cli-chat acp). Like OpenGAP, acpx treats Kiro as a target, not a platform.

ACP as Standard Protocol

No seed framework implements ACP (Agent Client Protocol). The 11 seeds use MCP (tools), git (state), or markdown (behavior). acpx introduces ACP as a third category: structured agent-to-agent communication protocol. This is neither a tool protocol (MCP) nor a state protocol (git) — it is an interaction protocol between running agent processes.

Prompt Queueing at Protocol Level

acpx's IPC-based prompt queue is unique in the corpus. Other frameworks either:

• Block until the agent is free (synchronous)
• Spawn parallel agents for concurrent work

acpx allows true prompt queueing: submit-and-forget to a busy agent, with guaranteed in-order execution. No polling loop, no separate job queue infrastructure. This is a novel primitive for agent orchestration.

17-Agent Registry

acpx ships with registered adapters for 17 coding agents spanning 8+ vendors. No other framework in the corpus (batch or seeds) maintains a cross-vendor agent adapter registry. The closest analog is OpenGAP's 12 export adapters, but those are for framework format conversion, not live agent protocol routing.

System Prompt Override for Sub-Agent Role Assignment

--system-prompt and --append-system-prompt allow the orchestrating agent to reconfigure the sub-agent's identity dynamically, without defining separate agents. This "dynamic role assignment" pattern has no equivalent in any seed framework:

# Same codex agent, temporarily reassigned as security auditor
acpx --system-prompt "You are a security auditor..." codex exec "audit auth"

Structured Exit Codes

acpx's 7-code exit code taxonomy (0=success, 1=error, 2=usage, 3=timeout, 4=no-session, 5=permission-denied, 130=interrupted) is designed for orchestrator use. No seed framework defines machine-readable exit codes for agent interactions. This enables branch-on-failure in shell pipelines and CI workflows without parsing output.

What It Does Not Do

• No agent identity or behavior definition (no SOUL.md equivalent)
• No LLM gateway or request routing
• No compliance or SOD enforcement
• No built-in tools (MCP servers)
• No cost tracking or optimization
• No web UI
• No prompt injection defenses (delegates to underlying agent)

acpx is infrastructure for agent-to-agent communication, not a framework for defining agent behavior. It is the "glue layer" between agents, not the agents themselves.