acpx

# acpx ## When to use this skill Use this skill when you need to run coding agents through `acpx`, manage persistent ACP sessions, queue prompts, override the Claude system prompt, prune stale sessions, consume structured agent output from scripts, or compose multi-agent workflows declaratively with `acpx/flows`. ## What acpx is `acpx` is a headless, scriptable CLI client for the Agent Client Protocol (ACP). It is built for agent-to-agent communication over the command line and avoids PTY scraping. Core capabilities: - Persistent multi-turn sessions per repo/cwd - One-shot execution mode (`exec`) - Named parallel sessions (`-s/--session`) - Idempotent session creation (`sessions ensure`) - Session retention controls (`sessions prune` with age filters and history cleanup) - Portable session export/import for moving records and history across machines - Queue-aware prompt submission with optional fire-and-forget (`--no-wait`) - Cooperative cancel command (`cancel`) for in-flight turns - Graceful cancellation via ACP `session/cancel` on interrupt - Session control methods (`set-mode`, `set <key> <value>`) - Agent reconnect/resume after dead subprocess detection - Prompt input via stdin or `--file` - Config files with global+project merge and `config show|init` - Session metadata/history inspection (`sessions show`, `sessions history`) - Passive replay and live observation (`sessions watch -s <name> --cursor <cursor>`; omit the cursor for retained history) - Local agent process checks via `status` - Stable ACP client methods for filesystem and terminal requests; filesystem paths preserve symlink/parent traversal order within the working directory - Stable ACP `authenticate` handshake via env/config credentials - Structured streaming output (`text`, `json`, `quiet`) with optional `--suppress-reads` - Prompt-response `_meta` preservation across direct, queued, compare, and embedded-runtime results - Built-in agent registry plus raw `--agent` escape hatch - Claude system prompt override via `--system-prompt` / `--append-system-prompt` - Optional ACP filesystem and terminal capability opt-outs via `--no-fs` and `--no-terminal` - Tool whitelist (`--allowed-tools`), turn cap (`--max-turns`), retry on transient failures (`--prompt-retries`) - Multi-agent flows via `acpx flow run` and the `acpx/flows` authoring API (`defineFlow`, `decision`, `decisionEdge`, `acp`, `action`, `compute`, `checkpoint`) ## Install ```bash npm i -g acpx ``` For normal session reuse, prefer a global install over `npx`. ## Command model `prompt` is the default verb. ```bash acpx [global_options] [prompt_text...] acpx [global_options] prompt [prompt_options] [prompt_text...] acpx [global_options] exec [prompt_options] [prompt_text...] acpx [global_options] compare <agent>... '<prompt_text>' acpx [global_options] compare <agent>... --file <path> acpx [global_options] cancel [-s <name>] acpx [global_options] set-mode <mode> [-s <name>] acpx [global_options] set <key> <value> [-s <name>] acpx [global_options] status [-s <name>] acpx [global_options] sessions [list | new [--name <name>] | ensure [--name <name>] | close [name] | show [name] | history [name] [--limit <count>] | watch [-s <name>] [--cursor <cursor>] | export [name] --output <path> | import <archive> [--name <name>] [--cwd <dir>] | prune [--dry-run] [--before <date> | --older-than <days>] [--include-history]] acpx [global_options] config [show | init] acpx [global_options] flow run <file> [--input-json '<json>' | --input-file <path>] [--default-agent <name>] acpx [global_options] <agent> [prompt_options] [prompt_text...] acpx [global_options] <agent> prompt [prompt_options] [prompt_text...] acpx [global_options] <agent> exec [prompt_options] [prompt_text...] acpx [global_options] <agent> cancel [-s <name>] acpx [global_options] <agent> set-mode <mode> [-s <name>] acpx [global_options] <agent> set <key> <value> [-s <name>] acpx [global_options] <agent> status [-s <name>] acpx [global_options] <agent> sessions [list | new [--name <name>] | ensure [--name <name>] | close [name] | show [name] | history [name] [--limit <count>] | watch [-s <name>] [--cursor <cursor>] | export [name] --output <path> | import <archive> [--name <name>] [--cwd <dir>] | prune [--dry-run] [--before <date> | --older-than <days>] [--include-history]] ``` If prompt text is omitted and stdin is piped, `acpx` reads prompt text from stdin. ## Built-in agent registry Friendly agent names resolve to commands: - `pi` -> `npx pi-acp` (ACPX-owned package range; see `agents/Pi.md`) - `openclaw` -> `openclaw acp` (see the [OpenClaw guide](https://github.com/openclaw/acpx/blob/main/agents/OpenClaw.md)) - `codex` -> `npx -y @agentclientprotocol/codex-acp` (ACPX-owned package range) - `claude` -> `npx -y @agentclientprotocol/claude-agent-acp` (ACPX-owned package range; see `agents/Claude.md`) - `gemini` -> `gemini --acp` - `cursor` -> `cursor-agent acp` - `copilot` -> `copilot --acp --stdio` - `antigravity` -> `agy_acp_server.par` (`--uid=` on Linux; `agy_acp_server.exe` on Windows). Install the official runtime/helper pair and configure its own sign-in first; see [Antigravity](https://github.com/openclaw/acpx/blob/main/agents/Antigravity.md). Fixed-choice interaction questions are cancelled, including with `--approve-all`, host permission callbacks, and existing custom launchers; acpx cannot supply user answers through permission approval. - `devin` -> `devin acp` - `droid` -> `droid exec --output-format acp` (`factory-droid` and `factorydroid` also resolve to `droid`) - `fast-agent` -> `uvx fast-agent-mcp acp` - `fx` -> `fx acp` (install and authenticate a provider first; see the [fx guide](https://github.com/openclaw/acpx/blob/main/agents/Fx.md)) - `grok-build` -> `grok agent stdio` - `iflow` -> `iflow --experimental-acp` - `junie` -> `junie --acp=true` (install and authenticate Junie first; see the [Junie guide](https://github.com/openclaw/acpx/blob/main/agents/Junie.md)) - `kilocode` -> `npx -y @kilocode/cli acp` - `kimi` -> `kimi acp` - `kiro` -> `kiro-cli-chat acp` - `mcode` -> `mcode acp` (install/authenticate MCode first; prefer `exec` for one-shot work, and require advertised ACP reload support for cross-invocation continuity) - `mux` -> `mux acp` via an ACPX-owned npm range - `opencode` -> `npx -y opencode-ai acp` - `pool` -> `pool acp` - `qoder` -> `qodercli --acp` Forwards Qoder-native `--allowed-tools` and `--max-turns` startup flags from `acpx` session options. - `qwen` -> `qwen --acp` - `trae` -> `traecli acp serve` - `zeroclaw` -> `zeroclaw acp` Rules: - Default agent is `codex` for top-level `prompt`, `exec`, and `sessions`. - Unknown positional agent tokens are treated as raw agent commands. - `--agent <command>` explicitly sets a raw ACP adapter command. - Do not combine a positional agent and `--agent` in the same command. - Gemini version checks, Copilot ACP support checks, and their startup diagnostics use the selected agent's working directory and child environment, including session environment and embedded runtime overrides. - Embedded host lifecycle admission also covers compatibility and diagnostic invocations. Correlate their events by `launchId`; one session can produce several adapter processes. Checks retire their owned processes and output pipes before settling. ## Embedded hosts When embedding ACPX, import `createAgentRegistry` from `acpx/agent-registry` and use `inspect(agentId)` to obtain installed launch facts without starting an agent. Treat `undefined` as uninspectable. Check the returned missing command/package requirements before acquiring a session; recheck when launching because installed files can change. Authentication and native model discovery belong to session acquisition. Custom registry names such as `constructor` and `__proto__` work with resolution, listing, and inspection. Without an explicit registry entry, unknown names remain raw commands. Use `getStatus({ handle }).models.availableModels` when present for native display names, and pass the selected opaque model ID, including any slashes, unchanged to `setModel`. Model changes validate against the connected session's advertised models, including after reconnect. `setConfigOption` applies the same validation when `key` names the advertised model option and returns that operation's native ACP response with the accepted `configOptions`. Use the response to update model and reasoning controls together. Embedded callers can identify unknown or ambiguous model failures with `isRequestedModelUnsupportedError(error)` and `error.reason === "unadvertised-model"`. When a Cursor alias matches multiple advertised variants, the error also has `ambiguous: true`; a selector with no advertised match omits that flag. Claude ACP retains its forwarding exception for selectors absent from its advertised list. Use `prepareFreshSession({ handle })` to persist a fresh-session request across restart, then ensure without `resumeSessionId`. Ordinary `close` retains session continuity; explicit remote discard requires the adapter’s optional close capability. Embedded controls save accepted settings with the current conversation. Turn finalization and one-shot cleanup wait for admitted controls, preserving final output, usage, and selections in the saved session. Ordinary `close` can return before active prompt cancellation finishes; the later save preserves its close/reset markers. An unprompted persistent session recorded as created through `session/new` may be replaced after an ACP internal load/resume error (`-32603`) so its first prompt or control can run with saved preferences. Explicit native resumes, older records without creation provenance, earlier prompts (including cancelled turns), agent output, legacy resume markers, or imported provenance forbid this recovery; an unsupported or missing session still fails with `SESSION_RESUME_REQUIRED`. For persistent sessions, compatible `ensureSession` calls may reuse an active record, including from permission callbacks during control reconnects. Changing its working directory, adapter invocation, or resume identity while turns or controls remain unfinished rejects with `ACP_SESSION_INIT_FAILED`; await that work or use a different key. After an active close, await its turn result before reopening. Idle replacement retires the old owner before initializing the successor; other records and distinct one-shot sessions remain independent. For installed entrypoints and prerequisites, read the matching [agent guide](https://github.com/openclaw/acpx/tree/main/agents). For resolver callbacks, custom command overrides, and lifecycle details, read [embedded agent discovery](https://github.com/openclaw/acpx/blob/main/docs/session-control.md#embedded-agent-discovery). ## Commands ### Prompt (default, persistent session) Implicit: ```bash acpx codex 'fix flaky tests' ``` Explicit: ```bash acpx codex prompt 'fix flaky tests' acpx prompt 'fix flaky tests' # defaults to codex ``` Behavior: - Uses a saved session for the session scope key - Auto-resumes prior session when one exists for that scope - If no session exists for the scope, exits with `NO_SESSION` and prompts for `sessions new` - Is queue-aware when another prompt is already running for the same session - On interrupt during an active turn, sends ACP `session/cancel` before force-kill fallback Prompt options: - `-s, --session <name>`: use a named session within the same cwd - `--no-wait`: enqueue and return immediately when session is already busy - `-f, --file <path>`: read prompt text from file (`-` means stdin) ### Exec (one-shot) ```bash acpx exec 'summarize this repo' acpx codex exec 'summarize this repo' acpx --model gpt-5.6-sol codex exec --config-option reasoning_effort=xhigh 'review this repo' ``` Behavior: - Runs a single prompt in a temporary ACP session - Applies `--model`, then repeatable `--config-option <key=value>` selections, before prompting - Fails before the prompt if the adapter rejects a requested config option - Does not reuse or save persistent session state ### Compare (multi-agent one-shot) ```bash acpx compare pi openclaw codex 'summarize this checkout' acpx --format json compare codex claude --file prompt.md ``` Behavior: - Runs the same temporary-session prompt against each listed agent - Runs agents serially in the requested workspace - Reuses the global `exec` controls: cwd, timeout, permissions, `--policy`, auth, terminal, retries, model/system options, and output format - `--format text` prints one summary table row per agent - `--format json` or `--json` prints `CompareRow[]` - `--format quiet` prints `<agent>\t<status>` per row - Does not create saved sessions or separate compare transcript directories ### Cancel / Mode / Config / Model ```bash acpx codex cancel acpx codex set-mode auto acpx codex set model gpt-5.6-sol acpx codex set reasoning_effort max ``` Behavior: - `cancel`: sends cooperative `session/cancel` through queue-owner IPC. - `set-mode`: calls ACP `session/set_mode`. - `set-mode` mode ids are adapter-defined; unsupported values are rejected by the adapter (often `Invalid params`). - On allowed fresh fallback, `set-mode` replaces the old saved mode without replaying it. Other saved settings restore first; the new mode preference is saved only after acceptance. - Prompt reconnect uses model metadata received while restoring a saved mode before replaying the selected model, and retains changed or removed model support in the final session metadata. - `set`: calls ACP `session/set_config_option`. - A config key named `mode` keeps config-option transport; explicit `set-mode` uses the separate `session/set_mode` control. - Current codex-acp releases expose `model` and `reasoning_effort` as separate config options. - `--model <id>`: Claude-compatible adapters may consume session creation metadata; other agents must advertise a model config option or legacy `models` metadata. - `set model <id>`: validates against the connected session's advertised models, uses `session/set_config_option` for model config options, and preserves `session/set_model` for explicitly advertised legacy models. Claude Code still accepts or rejects selectors absent from its advertised list. - Model switches can change or remove reasoning-effort controls. ACPX reconciles saved config selections with the accepted response; select a supported effort again if needed. - After reconnect, ACPX restores the saved model when advertised and replays saved config selections before prompting. A replay failure is reported instead of silently using defaults. - `set-mode`/`set` route through queue-owner IPC when active, otherwise reconnect directly. ### Sessions Use `acpx --format json pi sessions watch -s reviewer` to observe another client's work. Resume with `--cursor` using the last event's opaque cursor. Watchers do not cancel turns when stopped; use `turn_result` for the settled outcome, and treat owner-loss errors as unknown outcomes rather than retry instructions. See [Watching sessions](https://github.com/openclaw/acpx/blob/main/docs/session-watch.md). ```bash acpx sessions acpx sessions list acpx sessions list --filter-cwd . acpx sessions list --cursor <cursor> acpx sessions list --local acpx sessions new acpx sessions new --name backend acpx sessions ensure acpx sessions ensure --name backend acpx sessions close acpx sessions close backend acpx sessions show acpx sessions history --limit 20 acpx sessions export backend --output backend-session.json acpx sessions import backend-session.json --name backend-restored acpx sessions prune --dry-run --older-than 7 acpx sessions prune --older-than 30 --include-history acpx status acpx codex sessions acpx codex sessions new --name backend acpx codex sessions ensure --name backend acpx codex sessions close backend acpx codex sessions show backend acpx codex sessions history backend --limit 20 acpx codex sessions export backend --output backend-session.json acpx codex sessions import backend-session.json --name backend-restored acpx codex sessions prune --before 2026-04-01 --include-history acpx codex status ``` Behavior: - `sessions` and `sessions list` are equivalent