Supported coding agents

Supported coding agents

Most Shipper users arrive here with access to a coding agent already in place. This page is for setting up the agent you have, not for choosing a winner between agents.

Use shipper setup as the recommended deterministic path for recording the selected agent for Claude Code, Codex CLI, GitHub Copilot CLI, Grok Build, or OpenCode. Use shipper setup --assist for user-level assisted setup that records personal settings and provides guidance about verification commands, CI, hooks, and branch protections without writing repository files by default. Use shipper setup --assist --repo when you want the assistant to create or update agent instruction files, scaffold CI, author hooks, and configure branch protections. If you are not running shipper setup --assist, use Repository setup for agents as the manual fallback for those preparation tasks.

How Shipper selects an agent

Shipper uses commands.default.agent as the default coding agent for prompt-running commands. Per-stage commands.<stage>.agent overrides can select a different agent for individual workflow stages.

Shipper owns the per-agent launch command shapes in its bundled invocation matrix. Select agents through settings or one-run flags rather than wrapping the underlying agent CLI for Shipper runs.

See Reference > Settings for the settings schema and Switch coding agents for the switching workflow. Agent selection does not configure the MCP client itself; when you enable Shipper MCP tools in a client, follow the Shipper MCP client setup guide for client-specific timeout guidance.

Reasoning effort mapping

Set a default with commands.default.reasoningEffort, override an individual stage with commands.<stage>.reasoningEffort, or override one run with --reasoning-effort <effort>. The one-run flag has highest precedence, followed by the stage setting and then the default setting. When no value is configured, Shipper omits the option and leaves the agent’s native default intact.

Agent	Argument emitted by Shipper
Claude Code	--effort <value>
Codex CLI	-c model_reasoning_effort=<value> under exec
GitHub Copilot CLI	--reasoning-effort <value>
Grok Build	--reasoning-effort <value>
OpenCode	--variant <value> after opencode run arguments

For model precedence and per-agent argument placement, see One-run overrides.

Shipper does not maintain an allowlist of model or effort names. When persistent agent, model, or effort settings change, it instead runs a minimal invocation against the exact resolved agent and resulting tuple for each affected stage. A model rejection is definitive and refuses the write. Codex, Copilot, and Grok Build also report definitive effort rejections; Grok Build validates the effort against the selected model’s own menu, so a level one Grok model accepts can be rejected for another. Claude and OpenCode can succeed while silently substituting their default effort; Shipper writes those effort values but warns that they could not be confirmed and may be ignored. Distinct tuples share one 30-second overall verification deadline, including command preparation. An unavailable, unauthenticated, offline, or timed-out agent refuses the write unless the CLI-only --skip-agent-verification option is used. shipper settings check probes the stored effective tuples and reports the supplying settings file for any rejection.

OpenCode exposes --variant only for opencode run; Shipper rejects an effective reasoning effort before launching interactive or bare-root OpenCode invocations.

Observed model and effort identity

Alongside the model and effort it configured, each stage session records what the agent’s own run output reported it actually ran with. This is purely observational: it reads the transcript the run already produced, changes nothing about which model or effort runs, adds no flag, and adds no setting. The record shape and the three unresolved reasons are documented in Reference > .shipper directory.

Each agent is read through the best mechanism its own run output provides:

Agent	Observed model	Observed reasoning effort
Claude Code	system/init and root assistant records	No mechanism — never reported
Codex CLI	Its native rollout for the run’s thread id	Same rollout, per turn
GitHub Copilot CLI	Per root call in its run stream	Per root call in its run stream
Grok Build	Its native session summary for the run’s session id	Same session summary
OpenCode	Its native stored assistant messages	No mechanism — may be substituted

Only the model side is natively answerable for every agent. Because Claude reports no applied effort at all, and because Claude and OpenCode can both accept a configured effort while silently substituting their own, reasoning-effort cohorts on Claude and OpenCode are materially less trustworthy than model cohorts and should be read with corresponding suspicion.

Attended interactive runs generally leave no readable evidence and are recorded as no-evidence-for-run-mode. Coverage is the main stage session; models used by subagents a stage spawns are not separately attributed.

Shared cache access

By default, every supported agent receives the same machine-wide Shipper-owned npm, Turbo, uv, pnpm, Cargo, Playwright browser, Electron runtime, and electron-builder packaging environment used by install commands. All eligible locations are children of one common root; XDG_CACHE_HOME and general tool state remain worktree-private. The scoped grant applies in both headless and interactive modes:

Agent	Shared-root grant
Claude Code	--add-dir <shared-cache-root>
Codex CLI	--add-dir <shared-cache-root>
GitHub Copilot CLI	--add-dir=<shared-cache-root>
Grok Build	None needed — runs with --sandbox off
OpenCode	external_directory permission for root

Custom string-valued worktreeEnv cache variables retain operator ownership and are excluded from the shared marker. Supported per-worktree overrides include worktreeEnv.NPM_CONFIG_CACHE, worktreeEnv.TURBO_CACHE_DIR, worktreeEnv.UV_CACHE_DIR, worktreeEnv.PNPM_CONFIG_STORE_DIR, worktreeEnv.NPM_CONFIG_STORE_DIR, worktreeEnv.CARGO_HOME, worktreeEnv.PLAYWRIGHT_BROWSERS_PATH, worktreeEnv.electron_config_cache, and worktreeEnv.ELECTRON_BUILDER_CACHE. Shipper reports operator-owned overrides in one aggregate notice. A user-global sharedCache: false silently opts out machine-wide unless a narrower repository or personal true overrides it. If every shared-cache child fails, Shipper falls back to private paths and removes the root grant; if only some fail, the one grant still covers the healthy marked children. It does not delete the shared cache. All five supported agents receive equivalent access—none remains permanently isolated merely because its sandbox uses a different permission mechanism.

Sandboxed-stage temporary access

Sandboxed temporary storage is sandboxed-only and applies on macOS, Linux, and WSL2.

For a sandboxed Codex child, Shipper creates a fresh unique real directory named /tmp/shipper-cx-<24 lowercase hex> (on macOS, /private/tmp/shipper-cx-<24 lowercase hex> after canonicalization). That short path preserves Unix-domain socket path headroom. Shipper sets TMPDIR, TMP, and TEMP to this Shipper-managed path as the final environment source for that child only, after the inherited environment and all worktreeEnv values. An operator value cannot replace it. There is no setting, flag, or opt-out. Shipper does not mutate process.env or the operator’s shell.

For sandboxed Claude, Shipper prepares no temporary directory and does not override TMPDIR, TMP, or TEMP. Claude uses its native per-session temporary storage.

GitHub Copilot CLI, Grok Build, OpenCode, unsandboxed Codex and Claude, and any other invocation that Shipper does not sandbox retain their existing temporary environment.

Shipper deletes current and abandoned sandboxed Codex directories only when exact ownership is proven. Matching path, owner, device, and inode is insufficient because a successor directory may reuse them. For abandoned reclamation, both the Shipper process and Codex child must also be proven dead. When exact ownership cannot be proven, Shipper preserves the candidate, warns with its specific location, and continues the requested stage with fresh isolated storage.

If isolated temporary storage cannot be prepared safely, the stage does not launch. The operator receives a standalone error that identifies temporary-storage preparation as the cause. Cleanup failures warn with the affected location and do not change the stage result or fall back to shared or uncertain storage.

Shipper does not add --add-dir /tmp or widen Codex’s default writable roots, and does not promise exact-directory confinement. Codex may independently permit other system temporary directories through its own sandbox.

Claude Code

Fact	Details
CLI prerequisite	Install Claude Code, authenticate it, and make sure the claude command is available before Shipper can drive it.
Repository config file	Shipper expects CLAUDE.md for Claude Code. Bare shipper setup --assist explains what belongs in the file; shipper setup --assist --repo can create or update it and discover repository verification commands. The manual setup guide covers the fallback path.
Default Shipper behavior	When no eligible settings layer expresses an agent preference, the built-in defaults layer selects Claude. Shipper-dispatched worker stages — groom, design, the adversarial design review, plan, implement, and pr_review — run with MCP loading disabled by default for this agent; setup and new keep it enabled by default. Re-enable one stage with commands.<stage>.disableMcp: false, every stage with commands.default.disableMcp: false, or a single run with --enable-mcp. A one-run flag beats a per-stage value, which beats the default-scope value, and any explicit value beats the shipped default. An enabled stage prints MCP loading enabled for stage <name>.; a disabled stage prints no MCP policy line.
Practical implications	Claude Code is the only supported agent that uses CLAUDE.md. If a repository needs to support multiple agents, keep both CLAUDE.md and AGENTS.md current. The current Shipper MCP client setup guide includes Claude Code.

Codex CLI

Fact	Details
CLI prerequisite	Install Codex CLI, authenticate it, and make sure the codex command is available before Shipper can drive it.
Repository config file	Shipper expects AGENTS.md for Codex CLI. Bare shipper setup --assist explains what belongs in the file; shipper setup --assist --repo can create or update it and discover repository verification commands. The manual setup guide covers the fallback path.
Default Shipper behavior	When no eligible settings layer expresses an agent preference, the built-in defaults layer selects Claude. Select Codex with commands.default.agent, a per-stage override, or a one-run --agent codex flag. Shipper-dispatched worker stages — groom, design, the adversarial design review, plan, implement, and pr_review — run with MCP loading disabled by default for this agent; setup and new keep it enabled by default. Re-enable one stage with commands.<stage>.disableMcp: false, every stage with commands.default.disableMcp: false, or a single run with --enable-mcp. A one-run flag beats a per-stage value, which beats the default-scope value, and any explicit value beats the shipped default. An enabled stage prints MCP loading enabled for stage <name>.; a disabled stage prints no MCP policy line.
Practical implications	Codex shares AGENTS.md with Copilot, Grok Build, and OpenCode. Shipper handles the Codex command shape for Shipper runs, including worktree-specific behavior, so configure Shipper settings rather than wrapping the CLI yourself. The current Shipper MCP client setup guide includes Codex.

GitHub Copilot CLI

Fact	Details
CLI prerequisite	Install GitHub Copilot CLI, authenticate it, and make sure the copilot command is available before Shipper can drive it.
Repository config file	Shipper expects AGENTS.md for GitHub Copilot CLI. Bare shipper setup --assist explains what belongs in the file; shipper setup --assist --repo can create or update it and discover repository verification commands. The manual setup guide covers the fallback path.
Default Shipper behavior	When no eligible settings layer expresses an agent preference, the built-in defaults layer selects Claude. Select Copilot with commands.default.agent, a per-stage override, or a one-run --agent copilot flag. Shipper-dispatched worker stages — groom, design, the adversarial design review, plan, implement, and pr_review — run with MCP loading disabled by default for this agent; setup and new keep it enabled by default. Re-enable one stage with commands.<stage>.disableMcp: false, every stage with commands.default.disableMcp: false, or a single run with --enable-mcp. A one-run flag beats a per-stage value, which beats the default-scope value, and any explicit value beats the shipped default. An enabled stage prints MCP loading enabled for stage <name>.; a disabled stage prints no MCP policy line. For a stage that resolves to disabled, Shipper enumerates Copilot’s own MCP inventory with copilot mcp list --json and fails the run rather than launching with servers still attached if that inventory cannot be read.
Practical implications	Copilot shares AGENTS.md with Codex, Grok Build, and OpenCode. Shipper fails early with a missing-binary message if copilot is not on PATH. The current Shipper MCP client setup guide covers Claude Code, Codex, Grok Build, and OpenCode.

Grok Build

Fact	Details
CLI prerequisite	Install Grok Build (curl -fsSL https://x.ai/cli/install.sh | bash), make sure the grok command is available, and authenticate with grok login or XAI_API_KEY before Shipper can drive it. Shipper fails early with a missing-binary message if grok is not on PATH.
Repository config file	Shipper expects AGENTS.md for Grok Build. Bare shipper setup --assist explains what belongs in the file; shipper setup --assist --repo can create or update it and discover repository verification commands. The manual setup guide covers the fallback path.
Default Shipper behavior	When no eligible settings layer expresses an agent preference, the built-in defaults layer selects Claude. Select Grok Build with commands.default.agent: "grok", a per-stage override, or a one-run --agent grok flag. Shipper-dispatched worker stages — groom, design, the adversarial design review, plan, implement, and pr_review — run with MCP loading disabled by default for this agent; setup and new keep it enabled by default. Re-enable one stage with commands.<stage>.disableMcp: false, every stage with commands.default.disableMcp: false, or a single run with --enable-mcp. A one-run flag beats a per-stage value, which beats the default-scope value, and any explicit value beats the shipped default. An enabled stage prints MCP loading enabled for stage <name>.; a disabled stage prints no MCP policy line. When disabled for Grok Build, Shipper removes Grok’s two built-in MCP dispatchers with --disallowed-tools search_tool,use_tool, stops Grok from scanning Claude’s and Cursor’s MCP registrations by setting GROK_CLAUDE_MCPS_ENABLED=0 and GROK_CURSOR_MCPS_ENABLED=0 in the stage environment, and passes --deny MCPTool, which Grok enforces even under always-approve. No Grok configuration file is rewritten. Two limits follow from Grok’s own flag semantics: --disallowed-tools is headless-only, so an MCP-disabled interactive stage (new, groom, setup) relies on the deny rule and the environment overrides alone; and servers declared natively in ~/.grok/config.toml, .grok/config.toml, or a project .mcp.json still load as child processes, though the model cannot reach them.
Practical implications	Grok Build shares AGENTS.md with Codex, Copilot, and OpenCode. Shipper runs headless stages with grok -p <prompt> --output-format streaming-json --always-approve --no-plan --sandbox off --disallowed-tools ask_user_question --verbatim and starts interactive stages with --permission-mode acceptEdits --sandbox off --verbatim; the kernel sandbox is stated explicitly in both modes because Grok’s workspace profile would block the worktree’s git metadata in the parent clone and the shared cache root, and GROK_SANDBOX in the environment would otherwise change the default out from under an interactive stage. --verbatim is passed in both modes so an @path token in operator-authored issue or PR text is not resolved into an injected file attachment. New-issue screenshots are passed as file paths for Grok’s own file-read tool. Token usage is read from the terminal end (or error) record of the run stream.

OpenCode

Fact	Details
CLI prerequisite	Install OpenCode, make sure the opencode command is available, and authenticate with opencode auth login or provider API keys before Shipper can drive it.
Repository config file	Shipper expects AGENTS.md for OpenCode. Bare shipper setup --assist explains what belongs in the file; shipper setup --assist --repo can create or update it and discover repository verification commands. The manual setup guide covers the fallback path.
Default Shipper behavior	When no eligible settings layer expresses an agent preference, the built-in defaults layer selects Claude. Select OpenCode with commands.default.agent, a per-stage override, or a one-run --agent opencode flag. Shipper-dispatched worker stages — groom, design, the adversarial design review, plan, implement, and pr_review — run with MCP loading disabled by default for this agent; setup and new keep it enabled by default. Re-enable one stage with commands.<stage>.disableMcp: false, every stage with commands.default.disableMcp: false, or a single run with --enable-mcp. A one-run flag beats a per-stage value, which beats the default-scope value, and any explicit value beats the shipped default. An enabled stage prints MCP loading enabled for stage <name>.; a disabled stage prints no MCP policy line. When disabled for OpenCode, Shipper passes runtime OpenCode config overrides instead of rewriting user config files.
Practical implications	OpenCode shares AGENTS.md with Codex, Copilot, and Grok Build. Shipper runs headless stages with opencode run --format json --dangerously-skip-permissions, passes new-issue images with --file, and treats token usage as best-effort: usage is reported when OpenCode emits the expected token record and omitted without failing the run otherwise.