Settings reference

One window holds all of Birch’s settings (⌘, / Ctrl+,), organized into eight panes with a filter 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 eight panes — APPLICATION: General, Health · WORKFLOW: Git, Integrations, Task automation · AGENTS: Workspaces, Status integrations · ADVANCED: Advanced — under a Filter sections… box, which matches section names and related keywords (ssh, statusline, epic, …) and jumps to the first match. Each pane loads the first time you open it.

The footer is always Cancel + Save changes:

• Buffered edits — General, Health, Git identity and common git settings, Task automation, Workspaces (except Claude profiles) and Advanced — survive moving between panes. Save changes writes every pane you changed, in sidebar order, then closes. If one fails, the window stays on that pane with the error; panes saved before it stay saved, the rest stay unsaved for a retry.
• Immediate actions — accounts, Git credentials, the free-form git Set / Unset, Claude profiles, CLI and plugin installs — apply on click, and their panes say so: Cancel cannot undo them.

Cancel, Escape or closing the window discards unsaved edits on every pane, without asking. A pane whose data failed to load retries when you select it again, and Save changes won’t write it until a load succeeds, so a broken read can’t overwrite good values.

General

“Choose your editor and notifications.”

Section	Option	Default	Key
External editor	Radio: Visual Studio Code / Sublime Text / Custom command.	Visual Studio Code	editor.kind (vscode | sublime | custom)
External editor	Custom command, e.g. nvim {path} or /usr/local/bin/myeditor — {path} is replaced with the folder path, or the path is appended when the placeholder is absent.	empty	editor.customCommand
Teams notifications	Teams webhook URL (HTTPS; empty disables). Kept in the system keychain, not in settings — see Notifications.	empty	—
Teams notifications	Notify when someone approves / reviews or requests changes on / comments on my PR.	all off	notifications.teamsOnPrApproved / teamsOnPrReviewed / teamsOnPrCommented
Inbox notifications	Sound · desktop notification · app-icon count. See Notifications.	all on	notifications.inboxSoundOn / inboxDesktopOn / inboxBadgeOn

About & diagnostics (at the end of General) shows the Birch version with Copy version, Open logs folder and Report a problem… (all immediate; Report a problem… closes Settings first), and Offer to send a report after Birch closes unexpectedly (diagnostics.offerCrashReports, default on, saved as soon as you switch it). That option only controls the question Birch asks after a crash — nothing is sent without your click. See Report a problem.

Health

“Schedule focused work and regular breaks.” 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

Writes real git config and credentials, not Birch settings. Three tabs; when a repository is selected in the main window, the pane names it and adds per-repository controls.

• Identity — Global identity (Name / Email) and Global signing: Sign commits (commit.gpgsign), Key (user.signingkey), Format (openpgp / ssh); plus repository overrides of both. See Git identity & signing.
• Configuration — a Global / This repository toggle. Common settings (pull.rebase, core.autocrlf, credential.helper) save with Save changes; Add or update a key and the All entries list’s Set / Unset apply immediately.
• Credentials — the credential-helper status, HTTPS tokens per remote (Save / Forget) and the SSH key (Choose key… / Clear). See Git credentials.

Integrations

Six provider tiles — GitHub, GitLab, Jira, Azure DevOps, Linear, YouTrack. A tile opens its connected accounts (Sync now, Remove) and a connect form (Verify & connect; multiple accounts supported). Each form lists the Token permissions that provider needs above its create-token link; GitHub offers Create a classic token on GitHub ↗ and Create a fine-grained token ↗, and the GitHub and GitLab links open with those permissions already ticked. Tokens are stored in the system keychain and used only for API calls, never for git push or pull — see Storage & data and Providers overview. Git credentials are under Git → Credentials.

Task automation

With no account connected, the pane says only: “Connect an account in Settings > Integrations to configure this.”

Issue-status offers come first — two rows per account, “When a workspace starts from the task” and “When a PR is created from its workspace”, each with a mode picker, the remembered status (Remembered status: …) and a Reset. See Issue status transitions.

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}.

Inbox — “Hide task types you don’t want in the Inbox. Hidden tasks still sync, and unticking brings them back.” Per account, Hide these types: lists a checkbox for each type its tasks carry (ticked = hidden), and the box below adds one by name (e.g. Epic, Add or Enter). Where the tracker has sub-items there’s also a switch in its own word: Hide sub-tasks (Jira, YouTrack), Hide sub-issues (GitHub, Linear), Hide tasks (child items) (GitLab). Azure DevOps has no switch — hide Task by name; Linear has only the switch. Hidden tasks stay out of the Inbox and its Archive and never notify; a hidden parent’s children show at the top level. Keys: inbox.hiddenTypes.{accountId} (JSON array of names) and inbox.hideSubtasks.{accountId} (default false).

Workspaces

Option	Details	Default	Key
Agent command	Run in each new workspace terminal; empty means a plain shell. Also the Custom command agent’s command.	claude	terminal.agentCommand
Default shell (Windows)	PowerShell / Command Prompt (cmd.exe). Shown on Windows only.	PowerShell	terminal.defaultShell (powershell | cmd)
Agents	Claude / Codex / OpenCode / Custom command — which agents Birch offers.	all on	terminal.harness.{claude|codex|opencode|custom}.enabled

An agent switched off is hidden from both the create-workspace dialog and the tab strip’s ”+” menu; workspaces already created keep theirs. At least one stays on — the last ticked box is disabled.

Claude profiles run workspaces under several Claude accounts at once. The first row is your own ~/.claude; Add profile creates another with its own settings, skills, sessions and MCP servers (Rename, Test, Sign in…, Remove). Profile actions apply immediately.

Status integrations

All immediate.

• birch CLI — Install birch CLI to PATH, and Use this app’s CLI when a different birch comes first on your PATH. All three plugins need it. See CLI overview.
• Claude Code — Install plugin / Update / Uninstall for the birch-status plugin, plus Enable usage statusline, which points Claude Code’s statusLine at birch statusline (Usage statusline).
• Codex — Install plugin / Uninstall; then use /hooks in a new Codex session to review and trust the hooks.
• OpenCode — Install plugin / Update / Uninstall; a new OpenCode session loads it with no approval step.

Advanced

Update the base branch when creating a workspace (workspace.updateBaseBranchOnCreate, default off) — fetch and fast-forward the selected base branch first; diverged branches are never rewritten. Debug builds also show Co-authors (experimental.coauthors) and Skills & plugins explorer (experimental.skills, default on — see Skills).

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	The same one-time flag for the contextual “install the Codex status plugin” offer.
opencode.pluginPromptShown	true | false	unset	The same for the OpenCode status plugin offer.
opencode.pluginUpdatePromptedVersion	version string	unset	The OpenCode plugin’s update nudge — each new shipped version prompts once.

Note

The release channel is currently a settings key only.

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). terminal.permissionMode can also be planBypass — Plan + bypass, i.e. --permission-mode plan --allow-dangerously-skip-permissions.
terminal.codex.model / .effort / .sandbox / .approval, terminal.opencode.model / .agent	The same dialog, for Codex and OpenCode.
terminal.claudeCloud, terminal.claudeProfileId	The same dialog’s Claude cloud toggle and Claude profile.
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.