# acpx: a headless CLI client for stateful ACP sessions

> acpx wraps ACP-compatible coding agents behind one command shape, with persistent sessions under ~/.acpx/ and NDJSON output for automation. It is pre-1.0, so treat the CLI surface as moving.

**openclaw/acpx** — Headless CLI client for stateful Agent Client Protocol (ACP) sessions.

- Repository: https://github.com/openclaw/acpx
- Website: https://acpx.sh
- Stars: 3,286 · Forks: 340
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/openclaw-acpx

## The problem acpx solves for agent orchestrators

Running a coding agent from a script usually means parsing its terminal output. Each vendor ships its own interactive client, its own flags, and its own idea of what a turn looks like. acpx takes the other route: it is a headless client for the Agent Client Protocol, so the same command shape drives Codex, Claude Code, Gemini CLI, OpenClaw, or any custom ACP server you point it at with --agent. The audience is narrow and specific. It is for people writing orchestrators, CI jobs, or internal tooling that needs to send a prompt to an agent, keep the conversation alive between invocations, and read the result as data rather than as coloured text. The README frames the goal as one structured interface for persistent sessions, one-shot runs, permissions, and machine-readable output. The project is pre-1.0, and the README says to treat the CLI and runtime interfaces as evolving. That warning is the first thing to weigh, because the value proposition is exactly the surface that is still moving.

## How sessions persist and how output is shaped

The mechanism is a session store on disk. Session state lives under ~/.acpx/, and a session is scoped to the current repository, which persists across invocations. That scoping is what makes the second command in a workflow meaningful: the agent still knows what it read in the first. Named sessions let you keep parallel workstreams apart, and the README states that follow-up prompts are queued when a turn is already running, so two scripts writing to the same session do not simply collide. The other half of the mechanism is output. Text is the default. --format json emits NDJSON ACP events, which retain thinking, tool calls, diffs, and completion state instead of terminal escape sequences, and --format quiet prints only the final assistant text. A --cwd flag sets the session scope and the filesystem boundary, and permission modes run from read approval through explicit deny or approve-all. Global and project JSON configuration can supply defaults, with command-line flags taking precedence. For multi-step work there is a second layer: acpx flow run executes TypeScript workflows that mix ACP turns with deterministic actions, decisions, computation, and checkpoints. The package also exports acpx/runtime and acpx/flows for applications that want the primitives without shelling out.

## Installing acpx and running a first session

The published package installs globally from npm, and it requires Node.js 22.13 or newer. The README notes that prefixing a command with npx acpx@latest avoids the global install. Adapter prerequisites, updates, and source builds are covered in docs/install.md, so check that page for whatever agent you intend to drive.

```bash
npm install -g acpx@latest
```

Before the first prompt, install and authenticate the coding agent itself. The README is explicit that the upstream agent must be installed and authenticated when its adapter does not provide that on its own. Then create a session inside the project you want the agent to work on:

```bash
acpx codex sessions new
acpx codex "find the slowest test and explain why"
```

The first command prints a session id. The second sends a prompt into that session, and the README's example output shows tool lines such as a completed Read call followed by the assistant text and a done marker. Creating the session explicitly is deliberate: the README says it prevents automation from starting an unexpected conversation. If you want no saved session at all, exec is the stateless path.

```bash
acpx codex exec "summarize this repository"
```

For a named workstream, pass --name at creation and select it later with -s. The same prompt can also be run across several agents, which docs/compare.md covers.

## Where acpx is the wrong tool

The clearest boundary is the pre-1.0 notice. If your integration cannot tolerate a renamed flag or a changed runtime export between minor releases, acpx is the wrong dependency today, and the release cadence in the changelog suggests the surface is still being worked on. There is a second boundary around the adapters. acpx does not ship the agents; it drives them. If the upstream agent is not installed and authenticated, or the adapter does not handle that step, nothing runs. That makes acpx a poor fit for an environment where you cannot install vendor tooling alongside your own. Session state under ~/.acpx/ is also a design commitment worth naming. It is convenient for a developer machine and awkward for a container that is rebuilt on every job: state that is meant to persist has to be mounted or exported, and the sessions guide covers export and import for that reason. Finally, the permission model is a policy layer, not a sandbox. The README describes modes that range from read approval to approve-all, and --cwd sets the filesystem boundary, but the documentation does not present these as a substitute for process-level isolation. If your threat model assumes a hostile agent, decide that separately.

## acpx compared with driving one agent's own CLI

The obvious alternative is to call the coding agent's own command-line tool directly and parse its output. That approach has real advantages: one fewer dependency, no protocol layer to learn, and no version lag between acpx and the agent it wraps. The difference in approach is where the structure lives. With a direct call, the shape of a turn is whatever that vendor decided to print, and anything you build on top is coupled to that vendor's formatting. With acpx, the turn is expressed as ACP events, so --format json gives you the same event categories regardless of which agent is behind the command, and the same session commands work across profiles. The trade is that you inherit acpx's own release cadence on top of the vendor's, and you depend on the adapter being current for whichever agent you use. If you only ever drive one agent and you are happy with its native output, the direct route is simpler and has fewer moving parts. If you need to swap agents, compare them on the same prompt, or feed structured events into another program, the protocol layer is the point of the tool.

## Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-08-28, which is recent. Releases v0.13.2, v0.13.1, and v0.13.0 landed between 2026-07-27 and 2026-08-28, so the project is being published regularly. Note that the version in package.json is 0.15.1 while the newest release listed is v0.13.2, so read the changelog rather than assuming a single number describes what you will get from npm. Upgrading is a global npm install away, but the version pin is your responsibility: the README's own install command uses acpx@latest, and for automation a pinned version is the safer choice given the pre-1.0 warning. Expect to re-read docs/CLI.md and the coverage roadmap when you move between minor versions. The licence is MIT, which is permissive and places few obligations on how you redistribute or embed the package. This is not legal advice; if you are embedding acpx/runtime or acpx/flows in a product, have your own counsel review the LICENSE file and any third-party dependencies it pulls in.

## Conclusion

Adopt acpx if you need one scripted interface across several ACP coding agents and you can pin a pre-1.0 release. Do not adopt it if you need frozen CLI semantics or you only ever use one vendor's own interactive client. Before rolling it into automation, verify the adapter prerequisites for your chosen agent in docs/install.md, confirm where session state lands under ~/.acpx/, and check the exit-code table in docs/exit-codes.md against the failures your scripts need to detect.

## FAQ

### What is openclaw acpx?

acpx is a headless command-line client for the Agent Client Protocol, published on npm as acpx. It gives agents, orchestrators, and developers one structured interface for persistent sessions, one-shot runs, permissions, and machine-readable output across ACP-compatible coding agents.

### Does Claude Code support ACP?

acpx ships a built-in launch profile for Claude Code, so the command shape acpx claude is listed among the supported agents. The README notes that the upstream agent must be installed and authenticated when its adapter does not provide that itself.

### Can OpenClaw have multiple agents?

The README lists OpenClaw as one of the built-in launch profiles alongside Codex, Claude Code, and Gemini CLI, and it documents running one prompt across multiple agents in docs/compare.md. Named sessions also let you keep parallel workstreams apart within a single agent.

### What are some common use cases for OpenClaw?

The README points at automation, orchestrators, and multi-step work. Concretely: persistent sessions for follow-up prompts, exec for stateless one-shot runs, --format json for NDJSON events consumed by another program, and acpx flow run for TypeScript workflows that mix ACP turns with deterministic actions and checkpoints.

### What is the current version of OpenClaw?

The repository's package.json lists version 0.15.1, while the newest release listed in the repository is v0.13.2 from 2026-08-28. Because acpx is pre-1.0, check the changelog for what changed between the release you pin and the one you upgrade to.

## Sources

- [Official documentation](https://acpx.sh)
- [Official README](https://github.com/openclaw/acpx#readme)
- [Project repository](https://github.com/openclaw/acpx)
- [Release notes](https://github.com/openclaw/acpx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openclaw-acpx