/use-acpx

name: acpx
description: Use acpx as a headless ACP CLI for agent-to-agent communication, always inside an isolated SubAgent. Use when running coding agents through acpx, managing persistent ACP sessions, queueing prompts, consuming structured agent output from scripts, comparing the same prompt across multiple agents, or composing multi-agent workflows with defineFlow/decision/decisionEdge. Never invoke the claude adapter (nested-instance blacklist).

acpx

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`)
• Multi-agent comparison (`compare`)
• 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-scoped MCP servers from an external file (`--mcp-config`)
• Session metadata/history inspection (`sessions show`, `sessions history`)
• Local agent process checks via `status`
• Stable ACP client methods for filesystem and terminal requests
• Stable ACP `authenticate` handshake via env/config credentials
• Structured streaming output (`text`, `json`, `quiet`) with optional `--suppress-reads`
• Built-in agent registry plus raw `--agent` escape hatch
• Claude system prompt override via `--system-prompt` / `--append-system-prompt`
• Optional terminal capability disable via `--no-terminal` for review-only flows
• Optional filesystem capability disable via `--no-fs` for agent-native file operations
• 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

npm i -g acpx

For normal session reuse, prefer a global install over `npx`.

Operating protocol (when loaded inside Claude Code)

CRITICAL: when this skill is loaded inside Claude Code, the following protocol governs every invocation. These rules override any upstream default or example in this document.

1. Run inside a dedicated, clean SubAgent

Every `acpx`-driven task MUST execute inside an isolated SubAgent launched for that task (e.g. via the Task/Agent tool), with its own fresh context. Do not run `acpx` work inline in the main conversation thread. Rationale: agent-to-agent calls are long, noisy, and token-heavy; isolating them keeps the parent context clean and lets the SubAgent return only the distilled result.

2. Never call the `claude` adapter

The `claude` built-in is blacklisted (see the registry rule below). Calling `acpx claude ...` spawns a nested Claude instance — forbidden. Route to a non-Claude agent instead.

3. Execution sequence

For each user request, follow this order inside the SubAgent:

1. **Discover available agents first.** Probe which ACP adapters are actually installed on this machine before choosing one. Run:

   acpx --help                                  # lists built-in agent names
   command -v codex gemini cursor copilot 2>/dev/null   # which CLIs are on PATH

Pick the first installed non-Claude agent that fits the task (`codex` is the default; fall back through `gemini`, `qwen`, `cursor`, `copilot`, `droid`, `opencode`, ...). Do not assume an agent is installed — verify, then use it.

2. **Dispatch the user's actual request** to the chosen agent (`prompt` for multi-turn, `exec` for one-shot, `compare` for cross-agent).

3. **Do not duplicate upstream skill content.** Before invoking an agent for a task, check whether the upstream `acpx` skill/reference material already documents the capability needed (e.g. session lifecycle, flow authoring, output formats, permission policies in `references/`). If it does, defer to that knowledge and run the documented command — do not re-derive or re-explain it. Only synthesize new steps when the request is not already covered upstream.

The SubAgent returns a short summary of what ran, which agent it used, and the distilled result — not the raw ACP stream.

4. Reflect on every result with a fresh blank SubAgent before acting

CRITICAL: never accept an `acpx` SubAgent's result as final. Whatever the acpx SubAgent returns — a review, an evaluation, a diff, a recommendation, or a "done" — is a *proposal* from an outside agent, not a verdict. Before acting on it, spawn a SECOND, independent, blank SubAgent and have it reflect on that result; only after the reflection returns do you decide the next step.

• The reflection SubAgent MUST be a brand-new agent (a fresh Task/Agent invocation) with no context of the acpx run, the original prompt, or the implementation. It is NOT the SubAgent that ran acpx, and it is NOT the main thread. Reusing the acpx SubAgent or judging inline destroys the independence that makes the reflection worth anything — producer and judge must be different agents.
• Give the reflection SubAgent only the artifact under review (the acpx output plus the relevant files/diff), not the reasoning that produced it. It must reach its own conclusion.
• The reflection drives the branch: **accept**, **rework** (re-dispatch to acpx with corrections), or **escalate** to the user. Example: after `acpx ... review`, the blank SubAgent