Settings reference

One window holds all of Birch’s settings (⌘, / Ctrl+,), organized into panes with a search box over them. This page walks each pane top to bottom, then lists the handful of keys that currently have no UI switch.

How the window works

The left sidebar groups ten panes — GENERAL: General, Health · SOURCE CONTROL: Git User, Git Config, Integrations, Tasks · AI: AI, Claude Code, Codex · ADVANCED: Advanced — with a Search settings… box above them.

The footer holds a single button, and Save applies to the section you’re viewing:

• On General, Health, Git User, Git Config, Tasks, AI, Advanced the button reads Save — it saves the visible pane and closes the window. For all of these except Git Config the footer is the only save path; Git Config also keeps its own in-pane buttons (Save common settings, per-row Set / Unset), and its footer Save runs the common-settings save.
• On Integrations, Claude Code, Codex it reads Close — those panes act immediately through their own buttons (connect, install, etc.), and anything typed but not submitted (e.g. a pasted token) is discarded on close.

Escape (or the header ✕) closes without saving. Edits on a pane you navigated away from are also lost on close — there is no cross-pane dirty tracking. A pane whose data failed to load refuses to save until a reload succeeds, so a broken read can’t overwrite good values.

General

“How Birch opens files in your editor of choice.”

Option	Details	Key
External editor	Radio: VS Code / Sublime Text / Custom command.	editor.kind (vscode | sublime | custom)
Custom command	Free text (e.g. nvim {path} or /usr/local/bin/myeditor); {path} is replaced with the file path, or the path is appended when the placeholder is absent.	editor.customCommand

An External tools section (Diff tool · Merge tool) is present but disabled — “coming soon”.

Health

“Work in intervals, with a real break in between.” See Health breaks.

Option	Default	Key
Remind me to take breaks	off	health.enabled
Work for (minutes, 1–240, step 5)	50	health.workMinutes
Then rest for (minutes, 1–60)	10	health.breakMinutes
Notify me when a break starts	on	health.notifyOn

Git User

Writes real git config, not Birch settings — see Git identity & signing. Global identity (Name / Email) and global signing — Sign commits (commit.gpgsign), the signing Key (user.signingkey), and the signature Format — are always shown; a per-repository override section (identity + signing) appears when a repository is in scope.

Git Config

A curated git-config editor with a Global / This repository scope toggle. The Common settings block covers pull.rebase, core.autocrlf, and credential.helper (e.g. osxkeychain / manager) with a Save common settings button; below it, Add/set a key takes any section.key + value with a Set button, and the full entries list offers per-row Set / Unset.

Integrations

Provider accounts and git credentials — see Providers overview and Git credentials. Six provider tiles (GitHub, GitLab, Jira, Azure DevOps, Linear, YouTrack) with per-provider connect forms (Verify & connect; multiple accounts supported) and, for connected accounts, a Sync now and Remove. Below a divider, the same pane manages git credentials: credential-helper status, per-remote HTTPS tokens, and the SSH key. Tokens are stored in the system keychain — see Storage & data.

Tasks

Issue-status prompts, one row per tracker account × surface (workspace launch / PR created). Each row shows the account, the surface, a mode picker, the remembered status (Remembered status: …), and a Reset.

Mode	Behavior	Key value
Ask each time	Prompt with the status dialog (default).	ask
Change automatically	Apply the remembered status silently. Offered only once a status has been remembered.	always
Never offer	Skip the prompt entirely.	never

Keys: issue.status.{launch|pr}.mode.{accountId} and issue.status.{launch|pr}.target.{accountId}. With no tracker account connected, the pane shows: “Connect a GitHub, GitLab, Jira, Linear, YouTrack or Azure DevOps account in the Integrations pane to configure this.”

AI

See AI in Birch for the two AI paths these options configure.

Section	Option	Default	Key
Code review	Automatically review new PRs — “Requires ANTHROPIC_API_KEY. Does not run on the first sync of a repository.”	off	review.autoTriggerOnNewPr
Agent workspaces	Agent command — the command auto-run in each new workspace terminal; empty means a plain shell. Also serves as the Custom harness’s command.	claude	terminal.agentCommand
Agent workspaces	Default shell (Windows) — PowerShell / Command Prompt (cmd.exe). Shown on Windows only.	PowerShell	terminal.defaultShell
Agent workspaces	New-tab harnesses — which agents the workspace tab strip’s ”+” menu offers: Claude / Codex / OpenCode / Custom command.	all on	terminal.harness.{claude|codex|opencode|custom}.enabled
Teams notifications	Webhook URL (“Leave empty to disable”) + four event toggles: review completes/fails, PR approved, PR reviewed/changes requested, PR commented.	all off	notifications.teamsWebhookUrl, notifications.teamsOn*
Inbox	Notification sound · desktop notification · app-icon badge. See Notifications.	all on	notifications.inboxSoundOn / inboxDesktopOn / inboxBadgeOn

Claude Code

Three action blocks (no footer Save — everything acts immediately):

• Plugin — Install / Update / Uninstall the birch-status plugin, with the installed version and the equivalent in-Claude commands as a hint (/plugin marketplace add https://github.com/aidmsu/birch-code → /plugin install birch-status@birch).
• birch CLI — install status + Install birch CLI to PATH. See CLI overview.
• Usage statusline — Enable usage statusline, which points Claude Code’s statusLine at birch statusline. See Usage statusline.

Codex

Same shape for the Codex CLI: Plugin (Install / Uninstall, plus a note to run /hooks to review and trust the hooks after a restart; hint commands codex plugin marketplace add https://github.com/aidmsu/birch-code.git → codex plugin add birch-status@birch) and the same birch CLI block.

Advanced

“Feature visibility and experimental options.” Currently one production toggle: Skills explorer (experimental.skills, default on) — shows/hides the Skills explorer surfaces. Debug builds show additional debug-only options here.

Keys without a UI

Key	Values	Default	Purpose
update.channel	stable | beta	stable	Auto-update release channel — see Updates.
claudeCode.pluginPromptShown	true | false	unset	Set once the first-run “install the Claude Code plugin” offer has been shown, so it never re-appears. Clear it to see the offer again.
claudeCode.pluginUpdatePromptedVersion	version string	unset	The shipped plugin version the update nudge last asked about — each new shipped version prompts once.
codex.pluginPromptShown	true | false	unset	Set once the contextual “install the Codex status plugin” offer has been shown, so it never re-appears. Clear it to see the offer again.

Note

The release channel is currently a settings key only; a UI switch is planned.

A few other keys have no Settings pane because their UI lives elsewhere — they remember a choice made in the dialog that owns them:

Key	Set from
terminal.harnessKind, terminal.model, terminal.effort, terminal.permissionMode	The create-workspace dialog (last-used agent, Claude model, effort, and permission mode — pre-select the pickers next launch).
pull.strategy.{repositoryId}	The Pull button’s strategy dropdown in the Git Changes tab (remembered per repository).
pr.titleGenerateConfirmed	”Don’t ask again” on the ✨ generate-title cost warning in the Create PR dialog.