acpx: A Headless CLI for Stateful ACP Sessions

What acpx Actually Solves

Most CLI tools for coding agents are interactive. They render terminal escape sequences, block on a turn, and lose context when the process exits. acpx targets a different user: an orchestrator, a CI pipeline, or another agent that needs to drive an ACP-compatible coding agent without a human at the keyboard. The README calls it a headless client, and the core value is a single structured interface for persistent sessions, one-shot runs, permissions, and machine-readable output. It is not a chat wrapper. It is a control plane for agent sessions. The intended audience is developers building automation, not end users chatting with a model. The distinction matters because the design choices, like NDJSON output and explicit session creation, only make sense in a scripted context.

How Sessions and One-Shot Runs Differ

The fundamental mechanism is the session. Creating a session with `acpx codex sessions new` returns a session ID, and that session persists across invocations. The README emphasizes that sessions are scoped to the current repository, which prevents automation from accidentally starting a conversation in the wrong context. You can name sessions for parallel workstreams, as in `acpx codex sessions new --name backend`, and then target them with `-s backend`. Follow-up prompts queue if a turn is already running, which is a useful property for concurrent automation. In contrast, `exec` runs a stateless, one-shot command with no saved session. The distinction is clear: use sessions when you need context continuity, use exec when you want a clean slate. Session state lives under `~/.acpx/`, which is a concrete detail worth noting for cleanup and backup purposes.

Output Formats and Permission Modes

Text output is the default, but `--format json` emits NDJSON ACP events, and `--format quiet` prints only the final assistant text. The README claims that output events retain structured thinking, tool calls, diffs, and completion state, which is a direct answer to the problem of parsing terminal escape sequences. For automation, JSON output is the key feature. Permission modes range from read approval to explicit deny or approve-all policies. The `--cwd` flag sets the session scope and filesystem boundary, which is a simple but effective way to constrain what the agent can touch. Configuration can be global or project-based, with command-line flags taking precedence. This is a sensible hierarchy, but the README does not show the actual config file format, so you will need to read the config docs to understand the exact keys.

Flows and Embedding for Complex Automation

For multi-step work, `acpx flow run` executes TypeScript workflows that combine ACP turns with deterministic actions, decisions, computation, and checkpoints. This is a significant departure from a simple CLI. It means you can write a script that interleaves agent turns with your own logic, not just fire a prompt and wait. The package also exports `acpx/runtime` and `acpx/flows`, which allow applications to use session and workflow primitives without shelling out. This is an embedding story: you can build acpx into your own Node.js application. The README points to architecture notes and examples, but does not show a flow example inline. For a developer evaluating this feature, the lack of a concrete snippet in the README is a gap. You will need to read the flows guide to understand the exact syntax and lifecycle.

Installation and Running Requirements

Installation is straightforward: `npm install -g acpx@latest`. The package requires Node.js 22.13 or newer, which is a specific and relatively recent version. If you do not want a global install, you can prefix commands with `npx acpx@latest`. After installation, you must install and authenticate the coding agent you want to use. The README lists built-in launch profiles for Codex, Claude Code, Gemini CLI, and OpenClaw, plus a custom option via `--agent '<command>'`. The command shape is consistent across agents: `acpx codex …`, `acpx claude …`, etc. The upstream agent must be installed and authenticated when its adapter does not provide that itself. This is a real operational dependency: acpx is a client, not a runtime. You still need the agent binaries and credentials.

Limitations and Wrong-Tool Cases

The most obvious limitation is that acpx is pre-1.0. The README explicitly warns that the CLI and runtime interfaces are evolving. That means breaking changes are possible between releases, and you should pin versions. Another limitation is that acpx only works with ACP-compatible agents. If your agent does not speak ACP, you cannot use acpx unless you build a custom ACP server, which is a non-trivial task. The README does not detail what happens when an adapter is missing or outdated, so you may hit silent failures. Also, the session state lives under `~/.acpx/`, which is a local directory. If you need to run sessions on a distributed system, you will have to handle state sharing yourself. For simple interactive use, acpx is overkill; a plain terminal client is easier. The queueing behavior, where follow-up prompts queue when a turn is running, could be surprising if you expect immediate execution.

Alternative Approaches and Comparisons

The most direct alternative is to use each agent's native CLI directly. For example, Codex has its own command-line interface that supports sessions and output formatting. The difference is that each native CLI has its own syntax, output format, and permission model. acpx provides a uniform layer across agents, so you can write one script that works with Codex, Claude Code, or Gemini CLI by just changing the agent name. Another alternative is to use the ACP SDK directly in your application, if one exists for your language. That would give you more control over the protocol, but you would lose the session management, permission policies, and flow engine that acpx provides. A third alternative is to build your own wrapper around the agent's API, but that is essentially reimplementing acpx. The trade-off is between a pre-1.0 tool that may change and a do-it-yourself approach that is stable but costly.

Maintenance, Upgrade Cost, and License

The project is MIT licensed, which is permissive and allows commercial use without restriction, though you should not treat this as legal advice. The repository shows recent releases: v0.13.2 in August 2026, v0.13.1 in August, and v0.13.0 in July. That indicates active maintenance, with roughly monthly releases. The development workflow uses pnpm with `pnpm install --frozen-lockfile`, `pnpm run check`, and `pnpm run check:docs`. There is a CI workflow referenced, but no details on coverage. The upgrade cost is tied to the pre-1.0 status. You should read the changelog for each release, and the README suggests checking the install guide for updates. The documentation is extensive, with separate guides for sessions, permissions, config, exit codes, and flows. That is a positive sign, but it also means you have to read a lot to understand the full behavior.

Editorial conclusion

Adopt acpx if you are building automation that needs persistent, scoped sessions with machine-readable output and permission controls across ACP-compatible agents. Do not adopt it if you need a stable 1.0 API, or if your agent is not ACP-compatible and you cannot run a custom server. Before committing, verify that your target agent's adapter supports the ACP methods you rely on, and review the evolving CLI and runtime interfaces in the docs at acpx.sh. The project is pre-1.0, so pin the version and test upgrades in a staging environment before rolling out.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes