v0.5.1 to v0.6.0

---

name: acpx-faq

description: Run coding agents (codex, claude, agy/Antigravity) through the acpx ACP CLI - the headless lane outside a herdr pane (no HERDR_ENV). Use before launching or prompting a subagent, and when a command fails, a session is not found, or a prompt is lost.

metadata:

categories: "agents, operations"

topics: "acpx, acp, agent-orchestration, troubleshooting, headless-agents"

openclaw:

homepage: https://github.com/tenequm/skills/tree/main/skills/acpx-faq

emoji: "🔌"

---

# acpx FAQ

## Syntax authority

Syntax comes from the binary, not this file. `acpx --skill show acpx` is the vendor

transcript. Retrieve in this order:

1. `acpx --help` / `acpx <cmd> --help` - the flags you are about to compose.

2. One topic: `acpx --skill show acpx | rg -B2 -A12 '<term>'`, or a section:

`acpx --skill show acpx | sed -n '/^## Sessions/,/^## /p'`.

3. Authoring something novel (a flow, an embedded runtime): dump ONCE to a scratch

file and grep that file.

This file repeats nothing the reference covers. It carries only what the reference

lacks: exit codes, failure semantics, traps, and per-agent recipes. If a syntax

question is not answered here, it is answered there - go get it, never guess a flag.

## When this lane

acpx is the headless out-of-process executor lane. Inside a herdr pane (`HERDR_ENV=1`)

prefer herdr (herdr-faq): it gives you screen reads and dialog detection. Everywhere

else (plain terminal, ssh, cron) herdr is untargetable and acpx is the lane.

In-session fan-out stays on the harness's own subagent tool.

## Invariants

1. **Global flags precede the agent subcommand** (`--cwd`, `--model`, `--approve-all`,

`--agent`, `--format`, `--timeout`, `--ttl`, `--mcp-config`). The subcommand accepts

only `-s`, `--no-wait`, `-f` (and `exec` also `--config-option`). A global flag

2. **`-s <name>` never creates a session.** It resolves one, walking from `--cwd` up

3. **`status` is not a turn signal.** It probes the queue-owner process, never the

agent, and keeps saying `running` after the turn has ended. Never gate automation

on it.

5. **`[done] end_turn` and exit 0 are not proof of success.** A content-filter kill,

an MCP load failure, or a truncated turn all end that way. Read the stream, or

require the agent to write a result file you can check.

6. **A persistent session leaves a resident process stack until you close it.** Every

## Per agent

**Default to `exec` for dispatched work.** `exec` runs a temporary session: no saved

record, not queue-aware, so it never elects a queue owner and leaves nothing to clean

up. Use `-s <name>` only to queue follow-ups onto a live run or to read

`sessions history` afterwards - and then the closing `sessions close` is part of the

recipe (invariant 6). One directory (ideally one worktree) per parallel executor:

sessions key on cwd.

```bash

D=/abs/real/dir # must exist: roots resolve through realpath

acpx --agent ~/.local/lib/antigravity-acp/agy_acp_server.par \

```

- **agy reads sibling files unprompted** - agents sharing a directory reproduce each

other's output. One directory per agent, and checksum any rerun before believing an

agreement number.

```bash

mkdir -p ~/.gemini/antigravity-acp

echo '{"auth":{"type":"oauth-personal"}}' > ~/.gemini/antigravity-acp/settings.json

```

- **Never pass a positional agent with `--agent`** - exit **2**.

- **Verification prompts: demand a bare reply and read the whole log.** agy routes

answers into brain artifact files, so a `tail` cannot tell "no tools" from

"answered elsewhere". Add "Do not create any files".

#### Linux / NixOS

### codex

```bash

D=/abs/dir

acpx --cwd "$D" codex sessions ensure --name work # idempotent; -s cannot create

acpx --cwd "$D" codex set model gpt-5.6-sol -s work

acpx --cwd "$D" codex set reasoning_effort high -s work

codex -s work 'Carry out ./brief.md. Write your report to ./report.md.' > run.log 2>&1 &

# ...after the run finishes and you have read what you need:

acpx --cwd "$D" codex sessions close work # ALWAYS - the run is not over until this returns

```

One-shot: `exec --config-option reasoning_effort=low` sets model and effort inline

(0.14.0+), applied after `--model` and before the prompt.

- The codex adapter floats on `^1.1.5` - behavior can change without an acpx upgrade.

- **OpenAI's content filter kills benign turns** that end clean (`[done] end_turn`,

exit 0). Vocabulary like race / sweep / exploit / attack in a filename, comment or

prompt triggers it. Read the transcript tail before believing completion; recover by

re-prompting the same `-s <name>` (context survives) with the artifact renamed

neutrally and the remaining steps listed explicitly.

- **Queue a follow-up onto a live session** by prompting the same name again - it runs

after the current turn. This is how you course-correct without relaunching.

- **Handing off to a human TUI**: `sessions close` first, then `codex resume

<sessionId>` (id from `sessions show` - it is the ordinary codex rollout id).

### claude

```bash

D=/abs/dir

acpx --cwd "$D" --model claude-opus-5 claude sessions ensure -s work

acpx --cwd "$D" --model claude-opus-5 --approve-all --suppress-reads --timeout 2400 \

claude -s work -f /abs/brief.md >> run.log 2>&1 &

# ...after the run finishes and you have read what you need:

acpx --cwd "$D" claude sessions close work # ALWAYS - the run is not over until this returns

```

- **Second account**: export `CLAUDE_CONFIG_DIR` and `CLAUDE_SECURESTORAGE_CONFIG_DIR`

before `acpx`; the child inherits them.

## Sessions

- Sessions key on **(agent command, absolute cwd, optional name)** - parallel

executors need their own directories, which also keeps per-session model and effort

settings from racing.

- `sessions close` is the teardown verb: marks the record closed, sends ACP

`session/close`, takes down the owner and adapter processes (see Teardown). Also

required before `codex resume` and `sessions export`.

## Completion

- the foreground stream's terminating `[done] end_turn`, plus the process exit code;

- best: a **result file** the brief required the agent to write - poll for the file.

`--no-wait` acknowledges enqueueing (`[queued] <id>`), which is neither delivery nor

completion - behind a running turn the prompt waits for the turn boundary.

## Teardown

- **Owners lingering with no `--ttl 0` on the command line**: check

`~/.acpx/config.json` - its `ttl` key sets the default idle TTL, and `"ttl": 0`

there disables the self-reap for every invocation.

- Closed records persist indefinitely; `sessions prune --older-than 7` on a cadence.

## MCP

**The file shape is not the standard one.** acpx wants a JSON *array* of named server

```jsonc

// RIGHT - an array, each entry carrying its own name

```

**A stdio server that dies only under agy is an MCP era mismatch, not an acpx fault.**

agy probes stdio with `server/discover` (MCP 2026-07-28 retired the `initialize`

handshake); a legacy server that *aborts* on the unexpected request kills the pipe

- **A live queue owner refuses a config change** (it carries the config path plus a

SHA-256 fingerprint): `sessions close` first.

- **`--mcp-config` replaces the whole set** - verify a config written for one adapter

on another with a one-shot `exec` that asks the agent to name its own tools.

## Limits

- **Incoming ACP messages cap at 64 MiB** since 0.15.1 (previously unlimited);

`ACPX_MAX_ACP_MESSAGE_BYTES` raises it, `0` disables.

- Pass long briefs as `-f <path>` or a path in the prompt, never inlined - inlined

content in a shell command is what a driving harness's classifier blocks on.

## What acpx cannot do

Structural, not bugs. Do not design around them.

- **An ACP session does not wake.** An externally injected message lands in the

transcript but starts no turn; the only inbound channel is acpx itself

(`-s <name>`, optionally `--no-wait`).

- **`codex queue --thread` does not reach an acpx-driven codex session** (it does wake

a plain interactive codex).

- **acpx-spawned Claude sessions bind no IPC socket**, so `ListAgents` /

`SendMessage` cannot see or reach them.

## Failures

| code | meaning |

|---|---|

| 0 | success (also `cancel` with nothing to cancel) |

| 3 | `--timeout` exceeded |

| 4 | no session found by the directory walk |

Error catalog - string -> fix:

(invariant 1).

- `Do not combine positional agent with --agent override` (exit 2) - drop the

positional `claude`/`codex`.

- `Invalid value for config option model: <id> (ACP -32603, adapter reported

- `502 Bad Gateway: Failed to connect to backend API` (agy, exit 0) - missing CA

bundle on NixOS; see Linux / NixOS.

- `already has an active writer (code -32600)` - `codex resume` while acpx still owns

the thread; `sessions close <n>` first.

- `Missing --skill action.` (exit 1) - `--skill` needs

`show|list|install|export|help`.

Silent failures worth an explicit check: content-filter kills and MCP load failures