Settings

The Settings panel is a sidebar-on-the-left / content-on-the-right modal that covers every globally configurable ShipCode option. It’s mounted from apps/desktop/src/renderer/components/SettingsPanel.tsx with navigation from SettingsSidebar.tsx.

All settings persist in the local SQLite DB under the single settings row. The full type is AppSettings in packages/shared/src/types.ts.

Sections

General

Setting	Default	Purpose
`theme`	`system`	Light / dark / follow OS
`fontStyle`	`dm-sans`	Renderer font family style
`fontSize`	13	Base renderer font size
`projectSortOrder`	`recent`	Sidebar project ordering — alpha / recent / added
`projectOpenTarget`	`cursor`	Default app for opening project folders
`telemetryEnabled`	`null`	Error-reporting consent: `null` waits for explicit first-launch consent, `true` allows Sentry, `false` disables it
`terminalOpenTarget`	`terminal`	Default app for opening terminal sessions
`terminalScrollback`	10000	Max lines retained in the Terminal drawer per thread
`worktreeRoot`	`~/.shipcode/worktrees`	Where isolated pipeline worktrees live — set to a blank string for legacy project-local behavior
`worktreeBranchFormat`	`shipcode/{id}-{slug}`	Branch template for generated issue worktree branches (non-issue worktrees use `shipcode/{slug}`)
`addProjectStartsIn`	—	Optional starting folder for the add-project file browser

Privacy and Error Reporting

ShipCode does not send crash or pipeline failure reports until you explicitly choose Allow in the first-launch error reporting dialog. Choosing Decline stores telemetryEnabled: false; choosing Allow stores telemetryEnabled: true. You can change the same setting later from Settings -> General -> Privacy.

When enabled and a Sentry DSN is configured, reports include failure metadata such as thread id, project id, GitHub issue number, pipeline phase, retry counts, and sanitized exception context. Reports do not include prompts, terminal output, raw agent logs, tokens, secrets, or local file contents.

Set SHIPCODE_TELEMETRY_ENABLED=false before launching the desktop app to disable reporting before runtime initialization. The environment override is authoritative: Sentry is not initialized, and the Settings toggle is shown as disabled by environment until the app is relaunched without that override.

Pipeline

Setting	Default	Purpose
`requireApproval`	false	App default for the human approval gate. Project and issue overrides can require approval for a narrower scope, or turn it off for a specific repo / issue
`revisionCount`	0	Default number of review → revise cycles before approval or execution. `0` skips plan review for the fastest path; per-project and per-issue overrides can raise or lower it
`maxConcurrentPipelines`	3	Workspace-wide active pipeline cap
`maxConcurrentExecutions`	3	Per-project execution cap after planning/approval
`pipelineSpeedProfile`	`smart_fast`	Default scheduling/execution profile
`agentRunModes`	programmatic (structured phases & Codex execute); interactive (Claude execute, terminal fixes, instant)	Per-provider, per-phase output transport. Programmatic streams `claude -p` / `codex exec --json`; interactive drives the official CLI in a terminal pane. Programmatic Claude execute requires the sandbox below; Claude terminal-fix/instant stay interactive (host tools, no sandbox path); Codex programmatic runs sandboxed via `codex exec`
`claudeExecuteSandboxEnabled`	true	Required to select Programmatic for Claude execute. Wraps `claude -p` in the `srt` OS sandbox (`@anthropic-ai/sandbox-runtime`, macOS Seatbelt / Linux bubblewrap) so file/shell/MCP access is confined to the worktree. When false, programmatic Claude execute fails closed. No effect on Codex or the tool-less structured Claude phases
`claudeExecuteSandboxNetworkPolicy`	`anthropic-github`	Outbound allowlist for the sandboxed execute run. `anthropic-only` = Anthropic API only; `anthropic-github` also permits GitHub + npm registry (branch pushes, dependency installs)
`claudeExecuteSandboxExtraWritePaths`	`[]`	Extra absolute / `~`-prefixed paths the sandbox may write to, beyond the worktree and temp dir
`plannerReasoningEffort`	`low`	Default planner effort. Exact options depend on the selected provider
`reviewerReasoningEffort`	`high`	Default reviewer effort. Exact options depend on the selected provider
`executorReasoningEffort`	`medium`	Default executor effort. Exact options depend on the selected provider
`verifierReasoningEffort`	`high`	Default verifier effort. Exact options depend on the selected provider
`autoRunPriorities`	`[]`	Priority filter for auto-run. Empty = all priorities. Example: `["p0", "p1"]`
`autoRunMaxTasks`	0	Maximum tasks launched by auto-run. `0` means all matching tasks
`githubPollingIntervalMs`	30000	GitHub polling interval when auto-pickup is enabled
`githubBotUsername`	—	Label filter used to skip issues already handled by the bot

Models

Setting	Default	Purpose
`executorModel`	`codex`	Default executor when no `shipcode:agent:*` label is present (claude / codex / openrouter)
`plannerModel`	`codex`	Global default planner model
`reviewerModel`	`codex`	Global default reviewer model
`verifierModel`	`codex`	Global default verifier model
`triageModel`	`claude`	Provider for board review / Backlog triage
`triageAutoApplyThreshold`	`0.85`	Confidence threshold for auto-applying triage labels
`prdRewriteCli`	`claude`	Format provider for PRD editing and automation prompt formatting

All four phase models are editable here. These are the global defaults that new projects inherit unless they opt into a project-level override.

Effort options are provider-specific:

Claude CLI: none, medium, high
Codex: low, medium, high, xhigh
OpenRouter: none, minimal, low, medium, high, xhigh

Override precedence:

Planner / Reviewer / Verifier: global settings -> project override
Executor: global settings -> project override -> issue override

Claude-heavy work should normally enter through an interactive issue terminal session. Autonomous no-label pipeline runs default to Codex so claude -p / Agent SDK credit is not consumed unless a user explicitly selects Claude for a phase or applies a Claude routing label.

The runtime tab shows Interactive CLI vs Programmatic output controls. Programmatic is intentionally disabled for now; the visible control reserves the setting shape without routing Claude through claude -p or an SDK wrapper while Anthropic’s billing behavior is in flux.

If an older stored value is no longer exact for the current provider, the UI shows the mapping explicitly instead of pretending it is supported. Kanban cards display the effective phase model plus the effective effort for the current phase.

OpenRouter-specific toggles (openrouterEnabled, tier defaults, per-phase overrides) are documented on the OpenRouter page.

Notifications

Setting	Default	Purpose
`notificationsEnabled`	true	Master switch
`notificationOsEnabled`	true	Fire native OS notifications
`notificationBadgeEnabled`	true	Show an unread count badge for Inbox items on the app icon
`notificationSoundEnabled`	false	Play a sound on events
`notificationEvents.approval`	on	Fire when a run needs human approval before execution
`notificationEvents.failed`	on	Fire when any phase fails
`notificationEvents.completed`	on	Fire when a PR is opened; the item stays in Inbox until dismissed
`notificationEvents.verificationExhausted`	on	Fire when the verifier runs out of retries

Auto-commit

Setting	Default	Purpose
`autoCommitEnabled`	true	Enables AI-generated commits from the Git tab
`autoCommitModel`	`openrouter/auto`	OpenRouter model used to group and write commit messages
`autoCommitMode`	`split`	Commit grouping behavior
`cleanupCriteria`	see defaults	Controls which merged/closed branches and worktrees appear in cleanup

Archived

Unarchive projects that have been hidden from the sidebar and restore locally archived issues. Archived projects retain all their threads, plans, and cost history.

Developer

Diagnostic actions for copying app/version info, opening Chrome DevTools, opening the log directory, and changing the file log level.

About

Version and update-track controls.

Shortcuts

Keyboard shortcut reference — not yet remappable. See the page itself for the current binding list.

Per-project settings

Some settings are per-project rather than global:

githubProjectUrl override for the Kanban board quick-link
Per-project requireApprovalOverride
Per-project revisionCountOverride
Per-project pipelineSpeedProfileOverride
Per-project prdQualityGate
Per-project planner / reviewer / executor / verifier model overrides
Per-project planner / reviewer / executor / verifier effort overrides
Per-project Discord/Telegram routing overrides
Repo memory/context generator settings
.shipcode/setup.json setup, verification, runtime QA, and env-file configuration

Issue-level overrides are narrower by design: the human approval gate, revision count, and phase models can be overridden from Issue Detail, and those overrides apply to the next run of that issue only.

Human Approval Behavior

Human approval resolves through inheritance:

app default in Settings
optional project override in Project Settings
optional issue override in Issue Detail
Mentioning “human approval” inside an issue body or PRD does not change runtime behavior by itself

Once a run is approved, ShipCode can still delay execution if that project’s execution slots are full. The UI treats that as Waiting, not Needs approval.

Approval decisions are made by the pipeline runtime, not by prompt text. For GitHub issue runs, the engine starts in autonomous mode and the effective inherited approval setting decides whether planning pauses before execution.

Troubleshooting logs

ShipCode writes a structured local event log at:


apps/desktop/logs/events.log

This file records pipeline starts, phase transitions, review outcomes, and approval-gate decisions. If a run behaves unexpectedly, ask the user to send events.log together with the thread or issue number.

OpenRouter — full OpenRouter-specific configuration reference
Project Settings — per-project overrides
Pipeline Overview — how Pipeline-section settings affect each phase