# https://github.com/openclaw/acpx Project Manual

Generated at: 2026-06-23 12:43:13 UTC

## Table of Contents

- [acpx Overview & System Architecture](#page-1)
- [Agent Registry & Built-in Adapters](#page-2)
- [Session Management, Queues & Lifecycle](#page-3)
- [Flows, CLI Surface, Permissions & Runtime](#page-4)

<a id='page-1'></a>

## acpx Overview & System Architecture

### Related Pages

Related topics: [Agent Registry & Built-in Adapters](#page-2), [Session Management, Queues & Lifecycle](#page-3), [Flows, CLI Surface, Permissions & Runtime](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md)
- [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)
- [examples/flows/pr-triage/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/pr-triage/README.md)
- [agents/README.md](https://github.com/openclaw/acpx/blob/main/agents/README.md)
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)
- [agents/Trae.md](https://github.com/openclaw/acpx/blob/main/agents/Trae.md)
- [src/cli/config.ts](https://github.com/openclaw/acpx/blob/main/src/cli/config.ts)
- [package.json](https://github.com/openclaw/acpx/blob/main/package.json)
- [conformance/profiles/acp-core-v1.json](https://github.com/openclaw/acpx/blob/main/conformance/profiles/acp-core-v1.json)
</details>

# acpx Overview & System Architecture

## Purpose and Scope

`acpx` (version `0.11.1`, per [package.json](https://github.com/openclaw/acpx/blob/main/package.json)) is a **headless CLI client for the Agent Client Protocol (ACP)** that lets AI agents and orchestrators drive coding agents over a structured protocol rather than scraping PTY output. The README frames it as "one command surface for Pi, OpenClaw ACP, Codex, Claude, and other ACP-compatible agents. Built for agent-to-agent communication over the command line." Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

Its scope covers four concerns:

1. **Session lifecycle** — persistent, repo-scoped sessions with named parallel workstreams.
2. **Prompt transport** — queueing, cooperative cancel, fire-and-forget, and crash reconnect.
3. **Configuration and policy** — global + project JSON config plus permission policies.
4. **Multi-step orchestration** — TypeScript `acpx/flows` runtime for multi-step ACP work.

The package distributes three entry points — `.` (CLI), `./runtime`, and `./flows` — all built from `src/cli.ts`, `src/runtime.ts`, and `src/flows.ts` for Node 22 ESM. Source: [package.json](https://github.com/openclaw/acpx/blob/main/package.json)

> ⚠️ The README explicitly warns: "`acpx` is in alpha and the CLI/runtime interfaces are likely to change." Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

## High-Level Architecture

```mermaid
flowchart LR
    User[User / Orchestrator] -->|acpx CLI| CLI[src/cli.ts<br/>Command surface]
    CLI -->|resolve| Config[~/.acpx/config.json<br/>+ .acpxrc.json]
    CLI -->|spawn queue owner| Runtime[src/runtime.ts<br/>Session + Queue IPC]
    Runtime -->|ACP stdio| Adapter[Built-in adapter<br/>e.g. codex-acp]
    Adapter -->|wraps| Agent[Underlying CLI<br/>codex / claude / pi / ...]
    CLI -->|flow run| Flows[src/flows.ts<br/>defineFlow runtime]
    Flows -->|acp step| Runtime
    Flows -->|action / compute| Local[Local shell or HTTP]
    Runtime -->|writes| Disk[(~/.acpx/sessions/<br/>~/.acpx/flows/runs/)]
```

The CLI binary at `dist/cli.js` is the only user-facing entry point. It parses arguments, resolves configuration (global `~/.acpx/config.json` plus project `.acpxrc.json`), and either spawns a queue-owner process that hosts an ACP child or executes a flow module through the `acpx/flows` runtime. Source: [package.json](https://github.com/openclaw/acpx/blob/main/package.json), [src/cli/config.ts](https://github.com/openclaw/acpx/blob/main/src/cli/config.ts)

Adapters are auto-downloaded via `npx` on first use — operators do not install adapter packages manually. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

## Core Subsystems

### Sessions and Queueing

Sessions are persisted under `~/.acpx/sessions/` and identified by a cwd scope plus optional `-s <name>`. The README documents the lifecycle:

- **Prompt queueing**: while a prompt is running, new submissions are queued and drained by the running `acpx` process.
- **Queue owner TTL**: default 300 s; `--ttl <seconds>` overrides it; `--ttl 0` keeps owners alive indefinitely.
- **`--no-wait`** submits to the queue and returns immediately.
- **`cancel`** sends cooperative `session/cancel` over queue IPC; returns `nothing to cancel` when idle.
- **Crash reconnect**: a dead pid triggers respawn + `session/resume` (when advertised) or `session/load`, falling back to `session/new`.
- **`Ctrl+C`** sends ACP `session/cancel` and waits briefly for `stopReason=cancelled` before force-killing.
- **`exec`** is always one-shot and never reuses saved sessions.

Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

Session-control JSON payloads always carry `acpxRecordId` and `acpxSessionId`, with `agentSessionId` present only when the adapter exposes a provider-native id. The text/quiet session id is the local acpx record id — do not assume it can be passed back to the native CLI unless `agentSessionId` is set. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

### Configuration

`acpx config init` writes a `~/.acpx/config.json` template; `acpx config show` prints the resolved global-plus-project config. Per [src/cli/config.ts](https://github.com/openclaw/acpx/blob/main/src/cli/config.ts), configuration fields are validated with explicit error messages — for example, `ttl` must be a non-negative finite number, `timeout` must be positive, and `queueMaxDepth` must be a positive integer. The function `defaultGlobalConfigPath()` resolves to `~/.acpx/config.json` and `projectConfigPath(cwd)` resolves to `<cwd>/.acpxrc.json`.

### Flows Runtime

`acpx flow run <file.ts>` executes a TypeScript module through the `acpx/flows` runtime and persists run state under `~/.acpx/flows/runs/`. The README identifies five step types:

- `acp` — keeps model-shaped work in ACP.
- `decision()` / `decisionEdge()` — constrained-choice ACP branching without a new node type.
- `action` — deterministic mechanics like shell or GitHub calls.
- `compute` — local routing or shaping.
- `checkpoint` — pauses for something outside the runtime.

Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md), [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)

Shipped examples include `echo`, `branch`, `shell`, `workdir`, `two-turn`, the larger `pr-triage` workflow (which requires an explicit `--approve-all` grant), and a React Flow-based replay viewer at `examples/flows/replay-viewer/`. Source: [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)

## Built-in Agent Adapters

`acpx` ships a registry of built-in adapters that map a short CLI name to an ACP-compatible child command. Per [agents/README.md](https://github.com/openclaw/acpx/blob/main/agents/README.md), currently documented built-ins include:

| Name | Adapter invocation |
| --- | --- |
| `pi` | `pi-acp` (wraps Pi Coding Agent) |
| `openclaw` | native `openclaw acp` |
| `codex` | `npx -y @agentclientprotocol/codex-acp` |
| `claude` | `npx -y @agentclientprotocol/claude-agent-acp` |
| `copilot` | `copilot --acp --stdio` |
| `droid` | `droid exec --output-format acp` (aliases `factory-droid`, `factorydroid`) |
| `fast-agent` | `uvx fast-agent-mcp acp` (new in 0.11.0) |
| `cursor` | `cursor-agent acp` |
| `gemini` | `gemini --acp` |
| `iflow` | `iflow --experimental-acp` |
| `kilocode` | `npx -y @kilocode/cli acp` |
| `kimi` | `kimi acp` |
| `kiro` | `kiro-cli-chat acp` |
| `mux` | `npx -y mux@^0.27.0 acp` |
| `opencode` | `npx -y opencode-ai acp` |
| `trae` | `traecli acp serve` |

Sources: [agents/README.md](https://github.com/openclaw/acpx/blob/main/agents/README.md), [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md), [agents/Trae.md](https://github.com/openclaw/acpx/blob/main/agents/Trae.md)

Unknown names are passed through as raw commands, and `--agent '<command>'` is the explicit escape hatch for ad-hoc binaries. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

## Community Notes

A frequently requested addition is an Antigravity (`agy --acp stdio`) adapter mirroring the existing `acpx claude` / `acpx codex` shape (community issue #362). The same pattern — a built-in name pointing at an ACP-spawning child command — is the contract any new adapter must satisfy. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

The 0.11.0 release also surfaced cost, token-usage breakdowns, and advertised command metadata on runtime status/events, reflecting ongoing embedding work. The conformance suite at `conformance/profiles/acp-core-v1.json` defines a draft `acp-core-v1` profile (version `0.3.0`) covering required cases such as `initialize.handshake`, `session.prompt.multi_turn`, `permissions.read.approved`, and `session.cancel.followup_prompt`. Source: [conformance/profiles/acp-core-v1.json](https://github.com/openclaw/acpx/blob/main/conformance/profiles/acp-core-v1.json)

## See Also

- `acpx` CLI Reference (full option catalog)
- Flows Architecture (`docs/2026-03-25-acpx-flows-architecture.md`)
- ACP Spec Coverage Roadmap (`docs/2026-02-19-acp-coverage-roadmap.md`)
- Individual adapter docs under `agents/`
- PR-triage flow spec at `examples/flows/pr-triage/README.md`

---

<a id='page-2'></a>

## Agent Registry & Built-in Adapters

### Related Pages

Related topics: [acpx Overview & System Architecture](#page-1), [Flows, CLI Surface, Permissions & Runtime](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md)
- [package.json](https://github.com/openclaw/acpx/blob/main/package.json)
- [agents/README.md](https://github.com/openclaw/acpx/blob/main/agents/README.md)
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)
- [agents/Claude.md](https://github.com/openclaw/acpx/blob/main/agents/Claude.md)
- [agents/OpenCode.md](https://github.com/openclaw/acpx/blob/main/agents/OpenCode.md)
- [agents/FastAgent.md](https://github.com/openclaw/acpx/blob/main/agents/FastAgent.md)
- [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts)
- [src/cli/compare-command.ts](https://github.com/openclaw/acpx/blob/main/src/cli/compare-command.ts)
- [skills/acpx/SKILL.md](https://github.com/openclaw/acpx/blob/main/skills/acpx/SKILL.md)
</details>

# Agent Registry & Built-in Adapters

## Overview

`acpx` ships as a headless CLI client for the Agent Client Protocol (ACP) and exposes a single, uniform command surface (`acpx <agent> ...`) for talking to many different coding agents. To keep that surface stable while the underlying agent CLIs diverge, the project maintains a small built-in **agent registry**: a curated set of short names that resolve to known ACP-compatible commands. The README describes the registry shape as a one-liner per built-in: `pi -> npx pi-acp`, `codex -> npx -y @agentclientprotocol/codex-acp`, and so on. Source: [README.md:1-120](). The canonical inventory is documented in `agents/README.md`, which lists every built-in and links each one to a per-harness Markdown file. Source: [agents/README.md:1-40]().

The registry exists for three concrete reasons visible in the source:

1. **Ergonomic shorthand.** Operators write `acpx codex ...` instead of `acpx npx -y @agentclientprotocol/codex-acp ...`. Source: [README.md:80-120]().
2. **Onboarding documentation.** Each entry has a dedicated `agents/<Name>.md` describing upstream package, default command, and adapter-specific runtime controls (e.g., ACP modes, advertised models). Source: [agents/Codex.md:1-12]().
3. **Harness-specific capability surfacing.** Adapter capabilities like `session/set_model`, advertised `models`, or `set_config_option` are documented per agent so callers know which CLI flag or subcommand to reach for. Source: [agents/Codex.md:5-12]().

Adapters are **auto-downloaded on first use** via `npx`, so users do not need to install adapter packages manually. Source: [README.md:60-80]().

## Built-in Adapter Catalog

The following table summarizes the built-in agents as of `acpx` v0.11.x. Every row is sourced from `agents/README.md` and the linked per-harness docs. Source: [agents/README.md:1-40](), [package.json:1-15]().

| Short name | Default command | Notes |
|---|---|---|
| `pi` | `npx pi-acp` | Pi Coding Agent bridge |
| `openclaw` | `openclaw acp` | OpenClaw ACP bridge |
| `codex` | `npx -y @agentclientprotocol/codex-acp` | Advertised `models` + `set_config_option`; reasoning effort encoded in model id (e.g., `gpt-5.2[high]`) |
| `claude` | `npx -y @agentclientprotocol/claude-agent-acp` | Default range bumped to `^0.37.0` in v0.11.0 |
| `gemini` | `gemini --acp` | |
| `cursor` | `cursor-agent acp` | |
| `copilot` | `copilot --acp --stdio` | |
| `droid` | `droid exec --output-format acp` | Aliases: `factory-droid`, `factorydroid` |
| `fast-agent` | `uvx fast-agent-mcp acp` | Added in v0.11.0 |
| `iflow` | `iflow --experimental-acp` | |
| `kilocode` | `npx -y @kilocode/cli acp` | |
| `kimi` | `kimi acp` | |
| `kiro` | `kiro-cli-chat acp` | |
| `mux` | `npx -y mux@^0.27.0 acp` | |
| `opencode` | `npx -y opencode-ai acp` | |
| `qoder` | `qodercli --acp` | |
| `qwen` | `qwen --acp` | |
| `trae` | `traecli acp serve` | |

Per-harness notes (upstream URLs, advertised capabilities, model identifiers) are tracked in `agents/Codex.md`, `agents/Claude.md`, `agents/OpenCode.md`, `agents/FastAgent.md`, and the other sibling files. Source: [agents/Codex.md:1-12](), [agents/README.md:1-40]().

## Resolution Rules

`acpx` resolves an agent name through a layered lookup so unknown names still work as raw commands:

1. **Built-in lookup.** If the leading argument matches one of the registered short names (`codex`, `claude`, `opencode`, etc.), `acpx` substitutes the corresponding default command and passes through the remaining args. Source: [README.md:90-120](), [agents/README.md:1-40]().
2. **Raw-command fallback.** Any unknown agent name is treated as a literal command prefix. `acpx my-agent 'review this patch'` becomes `my-agent 'review this patch'`. Source: [README.md:90-120]().
3. **`--agent` escape hatch.** The global `--agent` flag lets callers bypass the registry and pin an exact command line, which is the right shape for local dev or CI profiles (e.g., `--agent './bin/dev-acp --profile ci' 'run checks'`). Source: [README.md:90-120]().
4. **`acpx exec` and `acpx flow run` reuse the same registry.** Because the registry is consulted before any subcommand, `acpx codex exec '...'` and `acpx codex flow run ./x.flow.ts` both resolve the same way. Source: [README.md:30-60](), [src/cli/compare-command.ts:1-40]().

The same flags (`--cwd`, `--approve-all`, `--approve-reads`, `--deny-all`, `--timeout`, `--format`, `--model`, `--policy`, `--non-interactive-permissions`) apply uniformly across all registered agents, defined in `src/cli/flags.ts`. Source: [src/cli/flags.ts:1-50](), [README.md:120-160]().

## Adding or Extending Adapters

Adding a new built-in is a lightweight, documentation-first change:

- Add the entry to `agents/README.md` with the form `<name> -> <default command>`. Source: [agents/README.md:1-40]().
- Create a sibling `agents/<Name>.md` describing the upstream package, default command, and any harness-specific runtime controls. Source: [agents/Codex.md:1-12]().

Recent releases show this pattern working at the registry level: `fast-agent -> uvx fast-agent-mcp acp` landed in v0.11.0 with the same one-line entry, and the Claude default range was bumped to `^0.37.0` without changing the short name. Source: [agents/README.md:1-40](), [package.json:1-15]().

Community requests for new built-ins (for example, issue #362 asking for an `antigravity -> agy --acp stdio` adapter) follow this exact template: pick a short name, identify a known ACP-stdio entry point, document the default command, and add a per-harness file. Source: [community discussion: #362].

## See Also

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md) — top-level usage and global flags
- [agents/README.md](https://github.com/openclaw/acpx/blob/main/agents/README.md) — built-in adapter inventory
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md) — Codex capability reference (advertised models, set_model vs set_config_option)
- [skills/acpx/SKILL.md](https://github.com/openclaw/acpx/blob/main/skills/acpx/SKILL.md) — paste-in skill block for delegating to other agents
- [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md) — flow authoring examples that compose any registered adapter
- [docs/CLI.md](https://github.com/openclaw/acpx/blob/main/docs/CLI.md) — full CLI reference (linked from `skills/acpx/SKILL.md`)

---

<a id='page-3'></a>

## Session Management, Queues & Lifecycle

### Related Pages

Related topics: [acpx Overview & System Architecture](#page-1), [Flows, CLI Surface, Permissions & Runtime](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md)
- [package.json](https://github.com/openclaw/acpx/blob/main/package.json)
- [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts)
- [src/cli/output/output.ts](https://github.com/openclaw/acpx/blob/main/src/cli/output/output.ts)
- [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)
- [examples/flows/pr-triage/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/pr-triage/README.md)
- [conformance/README.md](https://github.com/openclaw/acpx/blob/main/conformance/README.md)
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)
</details>

# Session Management, Queues & Lifecycle

`acpx` is a headless CLI client for the [Agent Client Protocol (ACP)](https://agentclientprotocol.com) that provides persistent, queue-aware session management for coding agents such as Codex, Claude, OpenClaw ACP, Pi, and OpenCode. Sessions survive across invocations, are scoped per working directory, and can be reloaded transparently if the underlying agent process dies. This page documents how sessions are created, addressed, queued, and shut down, drawing on the public CLI surface and flags described in the project README.

Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

## Session Addressing and Scoping

A session is identified by a combination of its working directory and an optional name. The `--cwd` flag sets the directory scope, and `-s <name>` (or `--session`) addresses a named session within that scope, enabling parallel workstreams in the same repo. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

Two pointer types are exposed through the CLI:

- **cwd-scoped default session**: implicit per-directory session used when no name is given.
- **named scoped session**: addressed by `-s <name>`, persisted under `~/.acpx/sessions/`.

Session selection flags are typed in `PromptFlags` and `SessionsNewFlags` and surface as Commander options:

```ts
export type PromptFlags = { session?: string; wait?: boolean; file?: string };
export type SessionsNewFlags = { name?: string; resumeSession?: string };
```

Source: [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts)

The lifecycle of a session includes creation, listing, inspection, history, resumption, closing, pruning, and reloading. The CLI exposes these via the `sessions` subcommand:

```bash
acpx codex sessions new --name api
acpx codex -s api 'implement token pagination'
acpx codex sessions list
acpx codex sessions show
acpx codex sessions history
acpx codex sessions ensure --name api
acpx codex sessions close api
```

`--filter-cwd` and `--local` provide pagination, cwd filtering, and saved-record inspection for `sessions list`. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

## Queue Owner, TTL, and Cooperative Cancel

Each session has a long-lived **queue owner** process that drains prompt submissions sequentially. When a second `acpx` invocation targets a busy session, the prompt is enqueued to that running owner rather than starting a parallel agent. Idle owners are kept alive for a configurable TTL (default 300 s) so follow-up prompts do not pay cold-start cost.

- `--ttl <seconds>` overrides the idle TTL; `--ttl 0` keeps the owner alive indefinitely.
- `--no-wait` submits to the queue and returns immediately without waiting for completion.
- `cancel` performs a cooperative `session/cancel` via queue-owner IPC; it succeeds with `nothing to cancel` if no prompt is running.

Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

The `SessionsPruneFlags` and `SessionsHistoryFlags` types in `src/cli/flags.ts` cover additional lifecycle maintenance:

```ts
export type SessionsPruneFlags = {
  dryRun?: boolean;
  before?: Date;
  olderThan?: number;
  includeHistory?: boolean;
};
export type SessionsHistoryFlags = { limit: number };
```

Source: [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts)

### Crash Reconnect and Soft-Close

If a saved session's pid is dead on the next prompt, `acpx` respawns the agent, attempts `session/resume` when the adapter advertises it (falling back to `session/load`), and only falls back to `session/new` if reconnecting fails. This preserves turn history across crashes. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

`close` performs a **soft-close**: it ends the live process without deleting history from disk, so the session can be re-opened or audited later. Each successful prompt appends lightweight turn previews (`role`, `timestamp`, `textPreview`) to the session metadata. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

`Ctrl+C` during a running turn sends ACP `session/cancel` and waits briefly for `stopReason=cancelled` before force-killing if needed. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

## Session Runtime Controls and Output Surfacing

The `set-mode` and `set <key> <value>` session controls route through queue-owner IPC when active, otherwise they reconnect directly to apply `session/set_mode` and `session/set_config_option`. Mode values are adapter-defined; unsupported values are rejected by the adapter, often as `Invalid params`. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

For adapters like Codex that advertise config options, model selection uses the adapter-advertised option:

> "acpx --model <id> codex ... and acpx codex set model <id> apply the requested model through the advertised config option; legacy adapters that advertise models use session/set_model."

Source: [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)

Runtime status and session events surface token usage breakdowns, cost, and advertised command metadata as part of embedding integration, so operators can inspect session economics from the CLI. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

### Queue and Lifecycle Flow

```mermaid
flowchart LR
    A[acpx invocation] --> B{Session exists<br/>in ~/.acpx/sessions/?}
    B -- No --> C[Start agent<br/>session/new]
    B -- Yes, alive --> D[Enqueue prompt<br/>via queue IPC]
    B -- Yes, dead --> E[Respawn agent<br/>session/resume or load]
    E -- Fails --> C
    D --> F[Queue owner drains]
    F --> G[ACP session/prompt]
    G --> H[Append turn preview<br/>role, timestamp, textPreview]
    H --> I[Idle TTL countdown<br/>default 300s]
    I -- new prompt --> D
    I -- TTL expires --> J[Soft-close]
    J --> K[History retained on disk]
```

Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

The `exec` subcommand is always one-shot and intentionally bypasses the saved-session lifecycle, which keeps it suitable for stateless automation. Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md)

## Flows: Multi-Step Lifecycle Beyond a Single Session

For multi-step work, `acpx flow run <file>` executes a TypeScript flow module through the `acpx/flows` runtime and persists run state under `~/.acpx/flows/runs/`. Flows combine ACP `acp` steps with deterministic shell-backed action steps (`workdir`, `shell`) and decision nodes. Source: [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)

Flows can target an explicit per-step cwd via the `acp` node so agent work stays inside disposable worktrees. The PR-triage example demonstrates a single persistent `main` ACP session across a judgment lane:

> "If the live ACP connection dies, the runtime should reconnect and try to load the same underlying agent session. If that resume fails, the workflow should fail clearly rather than silently starting a fresh persistent session and pretending context was preserved."

Source: [examples/flows/pr-triage/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/pr-triage/README.md)

This composes cleanly with the session lifecycle: a flow can own a named session (`-s triage`) and rely on `acpx`'s crash-reconnect semantics for that session across the flow's own steps.

## Conformance and Output Surface

A draft conformance suite under `conformance/` locks down session lifecycle behavior across adapters:

- `initialize`, `session/new`, `session/prompt`, `session/update`, `session/cancel`
- Baseline error semantics: `Invalid params`, permission denied, unknown session

Source: [conformance/README.md](https://github.com/openclaw/acpx/blob/main/conformance/README.md)

Rendered CLI output reflects lifecycle events: assistant text, thought traces, tool calls, plans, and a `done` marker. Status mapping and tool render state are defined in the formatter, where session notifications are extracted from JSON-RPC messages and tool updates are normalized before display. Source: [src/cli/output/output.ts](https://github.com/openclaw/acpx/blob/main/src/cli/output/output.ts)

## Common Failure Modes

- **Adapter does not advertise resume/load**: reconnect falls back to `session/new`, losing context. The pr-triage spec explicitly requires flows to fail clearly rather than silently restart.
- **Unsupported mode/config id**: rejected by the adapter, typically as `Invalid params`.
- **TTL expires mid-workflow**: a follow-up prompt will cold-start the agent; use `--ttl 0` for long-running flows.
- **`exec` is stateless**: it never reuses saved sessions and never updates history.

Source: [README.md](https://github.com/openclaw/acpx/blob/main/README.md), [examples/flows/pr-triage/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/pr-triage/README.md)

## See Also

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md) — full CLI reference and adapter catalog
- [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md) — flow authoring surface
- [conformance/README.md](https://github.com/openclaw/acpx/blob/main/conformance/README.md) — protocol-level conformance suite
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md) — adapter-specific session config options

---

<a id='page-4'></a>

## Flows, CLI Surface, Permissions & Runtime

### Related Pages

Related topics: [acpx Overview & System Architecture](#page-1), [Agent Registry & Built-in Adapters](#page-2), [Session Management, Queues & Lifecycle](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md)
- [package.json](https://github.com/openclaw/acpx/blob/main/package.json)
- [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)
- [examples/flows/pr-triage/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/pr-triage/README.md)
- [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts)
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)
- [agents/Trae.md](https://github.com/openclaw/acpx/blob/main/agents/Trae.md)
</details>

# Flows, CLI Surface, Permissions & Runtime

`acpx` is a headless CLI client for the [Agent Client Protocol (ACP)](https://agentclientprotocol.com) that lets AI agents and orchestrators drive coding agents over a structured protocol rather than scraping PTY output ([README.md](https://github.com/openclaw/acpx)). This page documents four tightly coupled subsystems: the **Flows** runtime for multi-step TypeScript workflows, the **CLI Surface** for command and flag handling, the **Permissions** model for tool approval, and the **Runtime** that owns session lifecycle, queues, and reconnect.

## Project Layout and Tooling

The published package exposes three entry points: `acpx` (the CLI), `acpx/runtime`, and `acpx/flows` ([package.json:42-49](https://github.com/openclaw/acpx/blob/main/package.json)). The build pipeline is driven by `tsdown`, targeting Node 22 ESM, with a `precommit` hook that runs `lint-staged` and a full rebuild ([package.json:50-58](https://github.com/openclaw/acpx/blob/main/package.json)). Lint coverage includes `oxlint` with type-aware rules, `oxfmt` formatting, a persisted-key-casing check, and a flow-schema-terms check that keeps the public flow vocabulary consistent ([package.json:62-66](https://github.com/openclaw/acpx/blob/main/package.json)).

## CLI Surface

The CLI is a single `acpx` binary that multiplexes over multiple built-in ACP adapters. Built-in names include `codex`, `claude`, `pi`, `openclaw`, and a generic escape hatch via `--agent '<command>'` for unknown harnesses ([README.md](https://github.com/openclaw/acpx)). Adapter metadata is declared in `agents/*.md`; for example, the Codex adapter uses `npx -y @agentclientprotocol/codex-acp` and advertises model ids such as `gpt-5.2[high]` ([agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)), while the Trae adapter runs `traecli acp serve` ([agents/Trae.md](https://github.com/openclaw/acpx/blob/main/agents/Trae.md)).

Flag types are defined in [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts). The relevant option groups are:

| Flag Group | Key Options | Source |
| --- | --- | --- |
| Global flags | `approveAll`, `approveReads`, `denyAll`, `cwd`, `format`, `timeout`, `ttl`, `verbose`, `model`, `systemPrompt`, `maxTurns` | `GlobalFlags` in [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts) |
| Prompt flags | `session`, `wait`, `file` | `PromptFlags` in [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts) |
| Session lifecycle | `name`, `resumeSession`, `cursor`, `filterCwd`, `output`, `destinationCwd` | `SessionsNew/List/Export/ImportFlags` in [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts) |
| Maintenance | `dryRun`, `before`, `olderThan`, `includeHistory` | `SessionsPruneFlags` in [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts) |

Common session subcommands follow a `acpx <agent> sessions ...` pattern: `new`, `list`, `show`, `history`, `ensure`, `close`, plus `status` for the local process view ([README.md](https://github.com/openclaw/acpx)). Prompts can be passed positionally, via `--file <path>`, or through piped stdin; `--no-wait` enqueues a prompt and returns immediately, while `Ctrl+C` sends a cooperative ACP `session/cancel` before falling back to force-kill ([README.md](https://github.com/openclaw/acpx)).

## Permissions

The permission model offers three explicit modes plus a structured policy override ([README.md](https://github.com/openclaw/acpx)):

- `--approve-all` — grant the agent broad tool access
- `--approve-reads` (default) — allow read-style operations and prompt for writes
- `--deny-all` — refuse tool use so the agent must answer without external actions
- `--permission-policy '<json>'` — pass a structured policy such as `{"escalate":["execute"],"defaultAction":"deny"}` to override defaults without code changes

A separate `--non-interactive-permissions fail` flag tells acpx to fail rather than deny when there is no TTY available to prompt ([README.md](https://github.com/openclaw/acpx)). For JSON output, `--format json` combined with `--json-strict` enforces machine-safe output; `--format quiet` is useful for "final recommendation only" runs ([README.md](https://github.com/openclaw/acpx)).

## Runtime and Sessions

The runtime owns persistent, cwd-scoped sessions that survive across CLI invocations, with named sessions enabling parallel workstreams in the same repo (`-s backend`, `-s frontend`) ([README.md](https://github.com/openclaw/acpx)). Lifecycle features include:

- **Prompt queueing** — additional prompts submitted while a turn is running are queued in order
- **Queue owner TTL** — `--ttl <seconds>` keeps the queue owner alive briefly for follow-ups
- **Soft-close** — `sessions close` ends the runtime process without deleting on-disk history
- **Crash reconnect** — dead agent processes are detected and the session is resumed or reloaded
- **Session controls** — `set-mode` and `set <key> <value>` map to `session/set_mode` and `session/set_config_option`, with `set model` routing to the advertised model config option when present ([agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md))

## Flows Runtime

`acpx flow run <file>` executes a TypeScript flow module through the `acpx/flows` runtime and persists run state under `~/.acpx/flows/runs/` ([README.md](https://github.com/openclaw/acpx)). The authoring surface, documented in [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md), exports flows via `defineFlow(...)` and imports helpers from `acpx/flows`. Flows compose five node kinds:

```mermaid
flowchart LR
    classDef acp fill:#e3f2fd,stroke:#1565c0,color:#0d47a1;
    classDef control fill:#fff3e0,stroke:#ef6c00,color:#4e342e;
    classDef action fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
    ACP["acp step<br/>ACP turn"]:::acp
    DEC["decision / decisionEdge<br/>constrained branch"]:::control
    ACT["action step<br/>shell / GitHub"]:::action
    CMP["compute step<br/>local routing"]:::action
    CHK["checkpoint step<br/>human pause"]:::control
    ACP --> DEC
    DEC -->|continue| ACT
    DEC -->|checkpoint| CHK
    ACT --> CMP
    CMP --> ACP
```

Flows keep model-shaped reasoning in `acp` steps, push deterministic mechanics (shell prep, GitHub API calls) into `action` steps, and use `decision()` plus `decisionEdge()` to wrap constrained-choice ACP branching without introducing a new node type ([README.md](https://github.com/openclaw/acpx)). `workdir.flow.ts` demonstrates flow workspace isolation — `acp` nodes can target an explicit per-step `cwd`, so flows can keep agent work inside disposable worktrees ([README.md](https://github.com/openclaw/acpx)). The larger `pr-triage` example intentionally keeps a single persistent `main` ACP session across its judgment lane so that reconnection after a dropped ACP connection resumes the same agent session; if resume fails, the flow fails clearly rather than silently spawning a fresh session ([examples/flows/pr-triage/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/pr-triage/README.md)). The PR-triage flow requires an explicit `--approve-all` grant and can comment on or close real GitHub PRs when run against a live repository ([examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)).

A browser-based replay viewer under `examples/flows/replay-viewer/` visualizes saved run bundles with React Flow, a recent-runs picker, and ACP session inspection ([examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)).

## Community Notes

Issue [#362](https://github.com/openclaw/acpx) requests an Antigravity (`agy`) adapter so that `acpx antigravity ...` mirrors the existing `acpx codex` / `acpx claude` / `acpx opencode` shape — a pattern consistent with the built-in adapter discovery described above. Release `0.11.0` (per the community context) bumped the default Claude ACP adapter range, surfaced cost, token usage, and advertised command metadata on runtime status/events, and added `fast-agent` as a built-in ACP adapter, all of which extend the runtime surfaces documented in this page.

## See Also

- [Quickstart / Installation](README.md)
- [Flow examples index](examples/flows/README.md)
- [PR-triage flow spec](examples/flows/pr-triage/README.md)
- [Codex adapter notes](agents/Codex.md)
- [CLI flag type definitions](src/cli/flags.ts)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: openclaw/acpx

Summary: Found 10 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

## 1. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/openclaw/acpx/issues/406

## 2. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://www.npmjs.com/package/acpx

## 3. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://www.npmjs.com/package/acpx

## 4. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/acpx

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://www.npmjs.com/package/acpx

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://www.npmjs.com/package/acpx

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/openclaw/acpx/issues/385

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/openclaw/acpx/issues/387

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/acpx

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/acpx

<!-- canonical_name: openclaw/acpx; human_manual_source: deepwiki_human_wiki -->