Skip to content
Shipper

Settings

Settings are stored in .shipper/settings.json (created by shipper init). Local overrides can be placed in .shipper/settings.local.json, which is gitignored.

| Setting | Default | Description | | ----------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | prReviewWait | { "mode": "checks", "minDurationMinutes": 15, "maxDurationMinutes": 30 } | PR review wait strategy. Timer mode uses { "mode": "timer", "durationMinutes": 30 } measured from PR creation time. Checks mode uses a JSON object such as { "mode": "checks", "minDurationMinutes": 10, "maxDurationMinutes": 30 }; minDurationMinutes enforces a minimum review window from PR creation time, an absent checks-mode minDurationMinutes defaults to 15 minutes, explicit values are honored exactly including 0, and omitting maxDurationMinutes waits indefinitely for checks. | | lockTimeoutMinutes | 30 | Stale lock timeout in minutes before shipper:locked is considered stale. | | agentTimeoutMinutes | 60 | Agent process timeout for headless runs in minutes. Set to 0 to disable the timeout. | | hookTimeoutMinutes | 10 | Hard timeout in minutes for file-based hooks and the worktree dependency-install command. Set to 0 to disable enforcement. Timeout aborts for pre-<stage>, worktree-setup, and the worktree install command; timeout warns and continues for post-<stage> and worktree-teardown. | | groomMaxQuestionRounds | 10 | Maximum question rounds per headless (MCP-driven) groom session. After the cap, the agent is restarted one final time and must compile the grooming artifacts, recording any unresolved product decisions under # Open Questions instead of asking more questions. | | commands | { "default": { "agent": "claude" }, "groom": { "disableMcp": true } } | Per-command settings map. default is required. Optional per-step overrides may set agent, mode, model, or disableMcp for new, groom, design, plan, implement, pr_open, pr_review, pr_remediate, unblock, and setup. CLI names with hyphens use underscores here, so pr-open, pr-review, and pr-remediate become pr_open, pr_review, and pr_remediate. | | commands.default.model | unset | Default model override for all supported prompt-running steps. | | commands.default.disableMcp | false | Default MCP loading policy for prompt-running steps. A per-step override can still flip any individual stage. | | commands.<stage>.disableMcp | groom: true; all other prompt-running stages unset/false | Per-stage MCP loading toggle. groom defaults to disabled MCP loading out of the box; every other prompt-running stage inherits normal MCP loading unless you opt in. | | defaultBaseBranch | auto-detected | Target branch for PRs if you do not set one explicitly. | | installCommand | unset | Shell command used for the advisory dependency-install step in new worktrees. Unset means no install command was configured. "" is a deliberate no-bootstrap setting written by setup after confirmation. .shipper/hooks/worktree-setup is the escape hatch for multi-step or hook-only bootstrap without adding a new settings schema. Executed via Node spawn(..., { shell: true }), which resolves to /bin/sh -c on macOS/Linux and cmd.exe (via %ComSpec%) on Windows. On Linux /bin/sh is typically dash; bash-specific syntax ([[ ]], arrays) will fail — wrap in bash -c "..." if needed. | | cliVersion | unset | Runtime Shipper CLI version fingerprint written by shipper init to record the CLI version that initialized the repository. It is one init-managed setting, not the full CI drift guard. | | worktreeEnv | unset | Environment variables applied inside worktree execution. Values are merged with built-in cache directory defaults. | | merge.requirePassingChecks | true | Require all CI checks to pass before auto-merging. |

Valid commands.*.agent values are "claude", "codex", "copilot", and "opencode". Claude Code uses CLAUDE.md for repository instructions. Codex CLI, GitHub Copilot CLI, and OpenCode use AGENTS.md.

For symptom-first recovery, see Troubleshooting for stale locks, worktree creation and install command failures, CLI version drift and version mismatch, agent and hook timeouts, and MCP tool loading issues.

Failure handling

Section titled “Failure handling”

If the agent discovers:

  • Missing prerequisites (gh, auth, labels) -> instruct shipper init and stop.
  • Missing product decisions during later phases -> recommend returning to shipper groom.
  • Missing technical decisions during implementation -> recommend returning to shipper design or shipper plan.
  • Oversized scope -> recommend splitting into additional issues created in shipper:new.

User repositories warn and proceed when the installed CLI is newer than the recorded cliVersion only within the same major version. They hard-fail for missing or unreadable fingerprints, installed CLI downgrades, and major-version drift; rerun shipper init to refresh the runtime fingerprint. The SHIPPER_SKIP_VERSION_CHECK runtime override is available as a temporary escape hatch, and 0.0.0-dev on either side bypasses the runtime check for development builds. Inside this Shipper repository, the runtime check still downgrades stale or missing fingerprints to a warning so contributors can finish in-progress CLI version bumps. CI and pre-push protection are handled by a broader .shipper/ init drift check; stale cliVersion is one possible drift, and remediation is to run shipper init and commit the resulting .shipper/ changes.

Built-in defaults are commands.default.agent = "claude" and commands.groom.disableMcp = true. Every other prompt-running stage defaults to normal MCP loading unless commands.default.disableMcp, a per-stage setting, .shipper/settings.local.json, or a one-run CLI flag overrides it.

Settings precedence is: built-in defaults -> .shipper/settings.json -> .shipper/settings.local.json. Prompt-running commands can also override agent, model, mode, and MCP loading for one run with CLI flags such as --agent, --model, --mode, --disable-mcp, and --enable-mcp. If the symptom is a version mismatch or MCP loading issue, use the CLI version drift and version mismatch or MCP tool loading issues troubleshooting sections.