Override settings

Start with user-global settings when you want to set a personal preference once for every repository. This is the least repetitive choice for an agent, model, or timeout preference:

shipper settings set commands.default.agent codex --user
shipper settings set agentTimeoutMinutes 0 --user
shipper settings set hookTimeoutMinutes 30 --user

Use 0 to disable a timeout. A more-specific committed repository or per-repository personal value can override these preferences.

Steps

Target one third-party or unlinked repository.

In a committed repository that you cannot or should not modify, including one protected by branch rules, use the personal scope:
Terminal window
```
shipper settings set generatedBranchPrefix feature/ --personal
shipper settings get generatedBranchPrefix
shipper settings set defaultBaseBranch integration --personal
shipper settings get defaultBaseBranch
shipper settings set baseIntegration merge --personal
shipper settings get baseIntegration
```
This creates feature/s43-* and feature/new-* branches without changing the repository’s committed files. Shipper resolves and creates the selected personal settings file for GitHub, unlinked, and non-GitHub repositories; you do not need to derive its path.

The personal defaultBaseBranch wins over a committed repository value and otherwise bypasses GitHub auto-detection. It is machine-local and does not modify the repository’s committed file. Its precedence is per-repository personal > committed repository > GitHub auto-detection. User-global --user scope is not valid for this key.

baseIntegration uses the same repository-or-personal scope rule. A repository can commit the shared strategy, while personal scope exists for a third-party repository whose committed settings you cannot change:
Terminal window
```
shipper settings set baseIntegration rebase --repo
shipper settings get baseIntegration
shipper settings set baseIntegration merge --personal
shipper settings get baseIntegration
```
The personal value wins over the committed value; when both are absent, Shipper defaults to rebase. User-global --user scope is invalid because this is repository behavior, not a per-developer preference.

Remove the personal branch override to reveal the committed value, or auto-detection when no committed value exists:
Terminal window
```
shipper settings unset defaultBaseBranch --personal
shipper settings get defaultBaseBranch
shipper settings unset baseIntegration --personal
shipper settings get baseIntegration
```
To remove the namespace, set an empty JSON string:
Terminal window
```
shipper settings set generatedBranchPrefix '""' --personal
```
Change the prefix only when no work is in flight. Shipper does not rename branches or remember an earlier custom prefix, so finish or reset affected work before choosing another value.
Configure shared worktree bootstrap.

Use committed repository scope when the team should run the same install command:
Terminal window
```
shipper settings set installCommand 'npm install' --repo
shipper settings set hookTimeoutMinutes 30 --repo
shipper settings get installCommand
```
installCommand is an overridable preference, so a user can still select a more-specific value. The --repo scope here establishes the shared team behavior.
Set repository-only policy.

Exactly five settings are repository-only: cliVersion, mirrorMode, transport, pullRequests, and reviewDelivery. They govern shared repository operation and version policy. Change them only with --repo:
Terminal window
```
shipper settings set mirrorMode store-only --repo
shipper settings set transport none --repo
shipper settings unset reviewDelivery --repo
```
Setup manages cliVersion; normally, refresh it by running shipper setup --repo and committing the resulting repository settings.

Inspect effective values and origins before correcting policy:
Terminal window
```
shipper settings get transport
shipper settings get pullRequests
shipper settings get reviewDelivery
```
An absent transport follows exact origin remote presence, and absent pullRequests follows effective transport. reviewDelivery is always "local"; a committed "post" warns for one release. Keep dependencies consistent: no transport requires no pull requests and store-only mirroring. These values define and report local policy now, but fully local workflow behavior is not operational until the remaining v4.2 work lands.

A committed base branch can still express shared team intent, but it remains personally overridable:
Terminal window
```
shipper settings set defaultBaseBranch main --repo
```
Opt a stage back in to MCP loading.

Shipper-dispatched worker stages run with MCP loading disabled by default, so the shared policy worth committing is usually an opt-in. Use committed repository scope when everyone should get the same MCP policy during a stage:
Terminal window
```
shipper settings set commands.implement.disableMcp false --repo
shipper settings set commands.default.disableMcp false --repo
shipper settings get commands.implement.disableMcp
```
The first command re-enables one stage and the second re-enables all nine. Because the shipped default varies by stage, commands.default.disableMcp reports <unset> until you set it — read a stage’s effective value with shipper settings get commands.<stage>.disableMcp. 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.

Choose a model and reasoning effort across repositories.

These are personal preferences, so use user-global scope when they should follow you everywhere:

shipper settings set commands.default.model opus --user
shipper settings set commands.default.reasoningEffort medium --user
shipper settings set commands.implement.reasoningEffort high --user

Remove a stage-specific value to reveal the next applicable value and its origin:

shipper settings unset commands.implement.reasoningEffort --user
shipper settings get commands.implement.reasoningEffort

Override an invocation without changing persistent settings.

One-run prompt flags are separate from stored scopes:
Terminal window
```
shipper implement S#43 --model opus --reasoning-effort high
```
The invocation value applies only to that run. Leaving the flag and persistent preferences unset keeps the selected agent’s native default.
Migrate a previously configured uv cache and control built-in sharing.

Shipper now shares uv automatically. If you previously followed the worktree-local UV_CACHE_DIR recommendation, inspect the effective value and supplying layer (use JSON when scripting), then unset it at exactly that layer:
Terminal window
```
shipper settings get worktreeEnv.UV_CACHE_DIR
shipper settings get worktreeEnv.UV_CACHE_DIR --json

# Run exactly one, matching the reported origin:
shipper settings unset worktreeEnv.UV_CACHE_DIR --user
shipper settings unset worktreeEnv.UV_CACHE_DIR --repo
shipper settings unset worktreeEnv.UV_CACHE_DIR --personal
```
Install-failure recovery clears covered cache variables that resolve anywhere inside the canonical worktree, not only beneath .shipper/tmp. Keep any UV_CACHE_DIR, pnpm store, or CARGO_HOME override outside the worktree when it must survive recovery.

To disable all built-in sharing machine-wide while allowing narrower exceptions:
Terminal window
```
shipper settings set sharedCache false --user
shipper settings set sharedCache true --repo
shipper settings set sharedCache true --personal
```

Require passing checks before merge.

Record shared merge behavior in committed repository settings:

shipper settings set merge.requirePassingChecks true --repo
shipper settings get merge.requirePassingChecks

Verification

Inspect one effective value and its origin with get:

shipper settings get commands.default.agent

Inspect the complete effective configuration, provenance, warnings, and selected settings-file statuses with list:

shipper settings list

See Reference > Settings for the full schema, persistent precedence, and repository-policy split.