Connect coding-agent CLIs

autodev communicates with coding agents by launching their command-line tools. The CLI runs locally in the story's isolated Git worktree, talks to its configured model provider, edits the checkout, and creates commits. autodev streams the process output, observes Git before and after the turn, and builds evidence independently of anything the agent says about its work.

Today, every bridge is CLI-based:

Bridge kind	Use it for	What autodev understands
codex	Codex CLI	Builds a non-interactive codex exec invocation and parses its JSONL result, failure, and usage events.
claude-code	Claude Code CLI	Builds a headless claude -p invocation and parses its stream-json result and usage events.
command	Pi, OpenCode, another coding-agent CLI, or a wrapper script	Substitutes the prompt into an argv template and observes the process and resulting commits. Harness-specific output remains a transcript; usage is unknown.

There is no direct OpenAI, Anthropic, or other model-provider API bridge yet. A direct API agent loop and its provider adapter are on the low-priority roadmap (A-160 and A-161). This is a future transport choice, not a weaker evidence path: direct API turns will still have to produce observable Git changes, transcripts, mechanical evidence, review, and a post-merge gate.

Prepare the CLI

Install the coding-agent CLI on the machine that runs autodev, then authenticate it as the same operating-system user and under the same HOME. autodev does not install a harness, perform its login flow, or place API keys in .autodev/fleet.toml.

Before involving the fleet, verify four properties in a disposable Git checkout:

1. the executable is on PATH in a non-interactive shell;
2. authentication works without a terminal prompt;
3. a one-shot invocation can edit files, run tools, create a Git commit, and exit;
4. success and failure produce reliable process exit behavior.

Run autodev init in the repository if .autodev/fleet.toml does not exist yet. The generated file contains a commented bridge template and is safe to run again: existing files are kept.

Configure Codex and Claude Code

Built-in adapters own the headless flags and structured-output parsing. A repository can use one harness for both roles or select different bridges and models:

.autodev/fleet.toml

[bridges.implementer]
kind = "codex"
model = "your-codex-model"
confinement = "fleet"

[bridges.reviewer]
kind = "claude-code"
model = "your-claude-model"
extra_args = ["--dangerously-skip-permissions"]
confinement = "fleet"

[roles]
worker = "implementer"
judge = "reviewer"

[validation]
argv = ["cargo", "test", "--workspace"]

Replace both model placeholders with identifiers accepted by the installed CLIs. worker and judge are separate turns even when they select the same bridge. Separate definitions make the reviewer's harness and model choice visible in configuration.

Permission flags are not a sandbox

Claude Code needs a non-interactive permission posture to modify a worker checkout. Its --dangerously-skip-permissions flag only changes the harness's tool-approval behavior. The confinement = "fleet" line is the filesystem boundary around the process; keep the two decisions distinct. Fleet confinement currently requires a working Bubblewrap installation on Linux.

Codex has a built-in workspace-write sandbox when confinement is omitted. Fleet confinement is recommended for a consistent recorded boundary and for repositories whose linked-worktree or nested sandbox operations do not work inside the Codex sandbox. Do not add sandbox-bypass or profile flags through extra_args; see Current limitations.

Configure Pi, OpenCode, or another CLI

Use kind = "command" when a coding agent has a one-shot headless command but no native adapter. Each {prompt} occurrence is replaced inside its argv element; the command runs with the story worktree as its current directory and with stdin closed.

Pi's print mode accepts a prompt as an argument. An ephemeral starting configuration is:

.autodev/fleet.toml

[bridges.pi]
kind = "command"
name = "pi"
argv = ["pi", "--print", "--no-session", "{prompt}"]
confinement = "fleet"

[roles]
worker = "pi"
judge = "pi"

OpenCode's run command is its non-interactive entry point:

.autodev/fleet.toml

[bridges.opencode]
kind = "command"
name = "opencode"
argv = ["opencode", "run", "--format", "json", "--auto", "{prompt}"]
confinement = "fleet"

[roles]
worker = "opencode"
judge = "opencode"

These are command templates, not native support promises. Check the installed version's CLI reference and smoke-test it: flags, permission behavior, and state locations belong to that harness. In particular, a generic CLI that must write session or authentication state outside the worktree may be refused by fleet confinement. Prefer an ephemeral mode or a small reviewed wrapper that keeps non-credential state in disposable storage. Configurable state mounts and a conformance probe for generic CLIs are tracked in A-162.

The generic adapter does not interpret the harness stream, inject model into argv, or translate [models] routing into vendor flags. Put a fixed model flag directly in argv if the CLI needs one, for example --model, using the syntax that CLI documents. Until a native parser exists, token usage remains explicitly unknown, never zero.

Environment and credentials

Harness processes start from a cleared environment. PATH and HOME pass through by default; declare only additional names the CLI or repository actually needs:

.autodev/fleet.toml

[env]
pass_through = ["RUSTUP_HOME", "CARGO_HOME"]

[env.set]
CARGO_TARGET_DIR = "target"
CI = "true"

Prefer the CLI's own credential store under HOME to passing provider secrets into every agent process. If a harness can authenticate only through an environment variable, add that exact name to pass_through and treat the choice as credential delegation: the harness and tools it launches can read it, and accidental output can enter the stored transcript. Never commit a token in fleet.toml.

Bind roles and validate the setup

Every worker needs a mechanical validation command. A judge is a distinct review turn; assigning a different named bridge is recommended when you want model or harness diversity.

After editing configuration, run:

autodev board check
autodev fleet status
autodev fleet disk
autodev fleet doctor

These commands exercise the shared configuration reader and name invalid bridge kinds, empty argv, missing role bindings, missing validation, or an unconfined role. Then place one small, reversible story in ready and run a single tick:

autodev fleet tick
autodev fleet status

Inspect the worker transcript, observed commit, evidence, and review before starting a long drive. A zero exit from the agent is not delivery by itself; the fleet still requires Git output and its configured proof path.

When configuration is refused

A command bridge does not claim that an arbitrary executable is sandboxed. Either configure confinement = "fleet", or deliberately accept the unconfined role in the driver's environment:

AUTODEV_ALLOW_UNSANDBOXED_ROLE=1 autodev fleet tick

The latter lets agent-authored commands reach everything available to the driver's user. It is an explicit risk acceptance, not a routine compatibility flag. Prefer fixing the headless invocation or state layout so fleet confinement can remain enabled. See Troubleshooting for the other typed configuration refusals.