Settings

Open settings with ⌘/Ctrl + , or from the sidebar. Settings are organized into sections.

General

Setting	Description	Default
App version	Shows the installed version and an inline Check for updates button. When an update is available, Install now / When idle buttons replace it.	—
Update channel	Build channel the updater follows: Stable or Beta. Opting into Beta is gated behind a confirmation dialog. Locked while an install is downloading or queued.	Stable
Worktree base directory	Directory where new workspaces are created	~/.workbench/workspaces
Default repository directory	Pre-fills the directory when adding or creating repositories. Both the Open Existing and Create New tabs in the Add Repository modal use this as the initial path.	Empty (no pre-fill)
Archive on merge	Automatically archive a workspace when its pull request is merged. See SCM Providers.	Off
Workbench Terminal	Show a read-only terminal tab that mirrors workspace provisioning (env-providers + setup script), agent shell commands, and background task output.	On
System tray	Enable/disable system tray integration	Enabled
Claude Code sign-in	Checks local Claude Code sign-in state with the official CLI. The refresh button performs an authenticated CLI validation request; sign-in runs claude auth login, streams progress back into Workbench, and accepts the pasted browser code when Claude Code asks for one. Used by chat and Usage-panel auth failures.	—
Yellow threshold (tokens)	Cache-read token count per turn that triggers the yellow cost warning icon in the composer	500000
Orange threshold (tokens)	Cache-read token count per turn that triggers the orange cost warning icon	750000
Red threshold (tokens)	Cache-read token count per turn that triggers the red cost warning icon	1000000
Tray icon style	Tray icon rendering: Auto, Light, Dark, or Color. Disabled when the system tray is off.	Auto
Automatically compact context on overflow	When a message fails because the context is too large, automatically compact the context and retry the same turn once. Disable to handle context overflow manually with /compact or by switching to a larger-context model.	On
Context overflow retry attempts	How many times to auto-compact and retry after a context-overflow error before giving up.	1
Overflow retry cooldown (seconds)	Minimum seconds between auto-compact retry attempts.	60s
Compaction timeout (seconds)	How long to wait for compaction to finish before marking recovery failed.	60s
Proactive compaction threshold (%)	Compact automatically when context usage reaches this percentage of the model window. Set to 100 to disable.	85%
Auto-retry on rate limit	Automatically wait and retry when a turn fails due to provider rate limits. Disable to surface the failure immediately instead.	On
Rate-limit retry attempts	How many times to retry a rate-limited turn before giving up.	3
Rate-limit base backoff (seconds)	Initial wait before the first retry; doubles each attempt.	5s
Rate-limit max backoff (seconds)	Upper bound on the wait between retries.	120s
Language	UI language: English, Spanish, Brazilian Portuguese, Japanese, Simplified Chinese, or German. See Internationalization.	English
Auth health check after inactivity	Checks Claude authentication status after this period of inactivity. Helps catch expired tokens before you start working. Options: Disabled, 1 hour, 2 hours, 4 hours, 8 hours.	4 hours

Apps

Controls for the workspace toolbar’s Open in app menu (the split button that opens the workspace in an editor, file manager, terminal, or IDE). Workbench auto-detects installed apps; these settings tune how they’re surfaced.

Setting	Description	Default
Default terminal	Terminal app used by Open in Terminal from workspace menus. Choose Auto to use the first detected terminal, or pick a specific detected terminal app.	Auto
Open-in menu	Choose which detected apps appear directly in the Open in app menu, and reorder them. Apps moved out stay reachable under the menu’s More flyout. Until you customize this, every detected app is shown; once customized, newly-installed apps are added under More. Use Reset to default to go back to showing everything.	Show all detected apps

Models

Default values applied to all new agent sessions. Per-workspace overrides are available in the chat header.

Setting	Description	Default
Default model	Model for new chats (Opus 4.8 1M, Opus 4.8, Sonnet 5, Haiku 4.5, Fable 5, Fable 5 1M; older models such as Opus 4.7 / 4.6 / 4.5 and Sonnet 4.6 / 4.6 1M remain selectable behind the picker’s “More” disclosure)	—
Default effort / Codex intelligence	Claude models use effort levels (auto, low, medium, high, xhigh, max where supported). Codex uses intelligence levels (low, medium, high, xhigh).	Auto / High
Default thinking	Enable extended thinking for Claude models. Codex does not expose a reasoning on/off toggle; use Codex intelligence instead.	Off
Show thinking / reasoning blocks	Display Claude thinking blocks or Codex reasoning summaries in the chat UI.	Off
Default plan mode	Start new sessions in plan mode. Claude-compatible sessions use Claude Code plan approval; Codex Native sessions use Codex plan collaboration mode.	Off
Default fast mode	Start new sessions in fast mode	Off
Team agents as session tabs	Open Claude Code team agents (TeamCreate + Agent with a team name) as separate Workbench chat session tabs.	On
Use Claude Code with Chrome	Allow Claude Code to control your Chrome browser. Requires the Claude Code Chrome extension to be installed first.	Off
Agent providers	Show Ollama, OpenAI API, and custom providers in Settings > Models and the chat model picker. Codex and Ollama are auto-enabled when detected unless manually disabled.	On
Codex	Show codex app-server --listen stdio:// support and seed Codex models into the picker. Independent from Agent providers.	On
Default backend	Provider used for new chats.	anthropic
Claude Code	Checks local Claude Code sign-in state with the official CLI. The refresh button performs an authenticated CLI validation request; sign-in runs claude auth login, streams progress back into Workbench, and accepts the pasted browser code when Claude Code asks for one. Used by chat and Usage-panel auth failures.	—
Agent backend cards	Enable, test, authenticate, and refresh model lists for built-in providers such as Claude Code, Codex, Ollama, and OpenAI API.	Provider-specific

See Agent Configuration for detailed descriptions of each option.

r26D

Company-specific settings for the r26D fork. See r26D Company Settings for full documentation.

Setting	Description	Default
Work Tracking	Enable work item tracking, pluck, and acceptance workflows in the sidebar. When off, the sidebar context menu hides work-tracking actions and the Work tab is not shown. Manual /xp_work commands remain available regardless.	Off

Experimental

Setting	Description	Default
Claude Code Usage	Surface Claude Pro / Max subscription quotas (5-hour session, weekly all-model, weekly Sonnet/Opus, extra usage) in the composer’s usage meter. The meter itself is always visible for Codex / OpenAI / OpenRouter / Ollama sessions (driven by local-aggregate token totals); this toggle only controls whether Claude-family sessions surface real subscription buckets versus a greyed-out click-to-enable affordance. Confirmation dialog warns about Anthropic ToS on enable.	Off

Claude Code Plugins, Community, and Collaboration are their own settings sections (visible by default in the Settings sidebar) rather than flat toggle lists — see Community Registry & Trust for the Community section. Claude Remote Control is reached from the chat composer’s overflow menu, not Settings. Legacy Experimental off values for these graduated features are ignored after upgrading and no longer hide their surfaces.

Automation

Native agent wakeups and routines are managed by the scheduler described in Agent Scheduling. The current surface is CLI and agent-tool driven; scheduled rows persist in the app database and re-arm when Workbench starts. Tasks whose workspace is archived or missing a worktree are paused with a visible reason rather than retried in the background.

Setting	Description	Default
Native scheduled routines	Agents can create one-shot wakeups and cron-style routines through the Workbench MCP bridge, and scripts can manage them with workbench routine.	On

Claude CLI Flags

Setting	Description	Default
Per-flag toggle	Enable or disable a specific claude CLI flag for all turns	Off
Per-flag value	Argument passed to value-taking flags (e.g. --permission)	—

Flags are discovered at startup from claude --help. Workbench’s own reserved flags (model, session ID, etc.) are excluded from the list. Enabled flags are appended to every claude invocation; disabled flags are omitted entirely.

Per-repo overrides are configured in Settings > Repository > Claude CLI flags and documented in Per-Repo Settings → Claude CLI Flag Overrides.

See Agent Configuration → Claude CLI Flags for full details and the chat-header chip display.

Appearance

Setting	Description	Default
Follow system	Match the OS light/dark appearance automatically. When on, separate Dark theme and Light theme pickers replace the single theme picker.	Off
Color theme	Active color theme when not following the system (16 built-in + custom).	Workbench Green
Dark theme / Light theme	Theme used for the dark and light appearances when Follow system is on.	—
UI font size	Interface font size. Also adjustable with ⌘/Ctrl + = / - and the View menu.	13px
Terminal font size	Font size for terminal tabs (8–32px)	11px
Group adjacent tool calls	Collapse adjacent regular tool calls and Agent invocations into summary blocks that start collapsed (even while still running). Click a chevron to expand. Live Agent groups keep status / count / latest tool visible while collapsed (rendered below the header) so long runs remain glanceable. When off, every top-level tool call, Agent call, and thinking block is shown inline and always expanded.	On
Extended tool call output	Add expandable, copyable input details under tool call rows.	Off
Terminal font size	Font size for terminal tabs (8–32px)	11px
Scrollback lines	Lines kept in memory per terminal tab. Range: 500–50,000. Default: 5,000.	5,000
Show running commands in sidebar	Surface in-progress shell commands for each workspace in the sidebar.	On
Interface font	Sans-serif font for the UI. Pick a detected system font or Custom… to enter a font family name.	System default
Monospace font	Monospace font for code, diffs, and the editor. Pick a detected system font or Custom….	System default

See Theming for details on built-in themes and creating custom themes.

Keyboard

Use Settings > Keyboard to review, rebind, or disable keyboard shortcuts. Disabled and rebound shortcuts are reflected in tooltips, command-palette labels, and the Keyboard Shortcuts reference.

Setting	Description	Default
Navigation shortcuts	Sidebar, diff panel, terminal panel, settings, fuzzy finder, command palette, tab, workspace, and project-jump shortcuts.	Platform defaults
Terminal shortcuts	Terminal tab, pane split, pane focus, copy/paste, terminal panel focus, and terminal-only zoom shortcuts. ⌘/Ctrl + Shift + = and ⌘/Ctrl + Shift + - adjust only the terminal font size.	Platform defaults
Voice shortcuts	Toggle recording and hold-to-talk shortcuts.	⌘⇧M / Ctrl+Shift+M; Right ⌥ on macOS for hold-to-talk

CLI

Setting	Description	Default
Install CLI on PATH	Installs (or reinstalls / updates / uninstalls) the bundled workbench command-line client to a directory on your PATH. When the installed copy is stale, the button offers an Update. If the target directory isn’t on PATH, a hint shows how to add it.	Not installed

See CLI Client for what the workbench command can do.

Pinned Prompts

Manage global pinned prompts — reusable prompt snippets available from the composer in every workspace. Per-repo pinned prompts are configured in Settings > Repository.

Notifications

Setting	Description	Default
Sound source	Where notification sounds come from: System sounds (your OS sound library) or OpenPeon sound packs (downloadable packs).	System sounds
Active pack	When OpenPeon is selected, the sound pack used for event sounds. Manage packs via Browse packs.	—
Volume	Playback volume for notification sounds (0–100%).	100%
Mute all sounds	Silence every notification sound without changing per-event selections.	Off
Event sounds	Per-event sound selectors for input required, plan needs review, agent finished, error, and session started. Each row has a preview button.	Default
User joined sound	Sound played when a remote user connects to your session (notification_sound_user_joined)	Inherits global
Notification command	Custom shell command to run on notification	—

Notification Sound

Each agent event (input required, plan acknowledgment, task complete, error, session start) has its own sound selector. Choose from built-in sounds or your system’s sound library:

• macOS: System sounds from /System/Library/Sounds/
• Linux: XDG sound theme sounds

Select None for an event to disable its sound, or use Mute all sounds to silence everything.

Notification Command

Run a custom shell command when a notification fires. The standard workspace environment variables are available, so your script can identify which workspace triggered the notification.

Example — send a Slack message:

curl -X POST "$SLACK_WEBHOOK_URL" \
  -d "{\"text\": \"Workbench: $WORKBENCH_WORKSPACE_NAME needs attention\"}"

Editor

Setting	Description	Default
Git gutter base	Which revision the editor’s git gutter compares your buffer against. Last commit (HEAD) shows uncommitted changes only; Workspace branch base shows every change made on this workspace’s branch since it diverged from the repository’s base branch (matches the Changes panel).	Last commit (HEAD)
Show minimap	Displays Monaco’s scaled-down file overview along the right edge of the editor.	Off
Reveal active file in Files tree	Auto-expands ancestor folders, highlights the active editor file, and scrolls it into view in the Files tree.	On

Git Gutter Base

The git gutter is the colored marker column to the left of line numbers in the file editor. By default it compares your editor buffer against HEAD, so the markers reflect uncommitted changes only.

If you’d rather see every change you’ve made in this workspace since branching from the repository’s base branch, switch to Workspace branch base. This matches the view in the Changes panel.

When the workspace is checked out on the base branch itself, “Workspace branch base” collapses to HEAD, so the gutter behaves identically. The setting is global — it applies to every workspace.

Diagnostics

Setting	Description	Default
Log level	File-log filter applied when RUST_LOG is unset. Bare levels are scoped to Workbench’s crates so dependencies stay below debug/trace, with mdns_sd capped at warn. Restart required for changes to take effect.	default (info,workbench=debug,workbench_tauri=debug,workbench_server=debug,mdns_sd=warn)
Frontend log verbosity	How much of the React side’s console.* output is mirrored into the daily log. Live — no restart needed.	Errors only
Reveal in file manager	Opens ~/.workbench/logs/ in the host file manager.	—
Copy path	Copies the log directory path to the clipboard.	—

When RUST_LOG is set in the process’s environment, the Log level select is disabled — the env var always wins. Uncaught browser errors and unhandled promise rejections are forwarded regardless of the Frontend log verbosity setting; the verbosity only gates the explicit console.* calls.

See Diagnostics & Logging for the full pipeline (where logs go, JSON output, per-domain RUST_LOG filtering, multi-instance behavior, bug-report workflow).

Storage

Setting	Description	Default
Clean up all (N)	Top-level action that opens the bulk cleanup modal in cleanup-all mode — every archived workspace across every local repository, grouped by repo. Disabled when nothing is archived.	—
Rescan	Re-runs the orphan scan and refreshes every per-repo size.	—
Repository card	One unified row per repository showing: icon + name, a total on-disk badge, and meta pills for active X, archived Y · N archived, and orphaned Z · N orphaned (only the pills that apply).	—
Per-workspace breakdown chevron	Expands a repo card to list every workspace under it (with per-workspace size + active/archived status) and every orphaned worktree dir attributed to that repo (with size + path + per-row trash).	—
Clean up… (per row)	Permanently deletes selected archived workspaces for that repo — worktree, branch, chat history. Lifetime metrics are preserved in deleted_workspace_summaries. Only rendered when the repo has at least one archived workspace.	—
Per-orphan trash icon	Inline destructive action on an expanded card. Opens a sticky confirm box at the bottom of the page, then permanently removes the orphan directory via std::fs::remove_dir_all. Refuses anything not strictly under the workspace base or still claimed by a workspace row.	—
Bulk orphan delete: Cancel	While a per-repo or “Delete all N orphans” purge is running, the Cancel button signals cooperative cancellation. The currently-running remove_dir_all finishes (the OS call can’t be safely interrupted partway), then the loop stops and every remaining orphan is preserved. The confirm box stays open with a partial-progress summary so the user can re-run on what’s left.	—
Unknown repository card	Synthetic card at the top of the list grouping orphans whose parent-dir slug doesn’t match any registered repository. Styled to call attention (red border, alert icon). Same per-orphan trash interaction as known-repo cards.	—
Checkpoint file retention	Per-workspace cap on how many recent checkpoints retain their file-restore snapshot. Older checkpoints stay visible in chat history but the “restore files” affordance is dropped for them — the underlying conversation_checkpoints and turn_tool_activities rows are preserved, only checkpoint_files rows are pruned. Clamped to [1, 1000].	50

The size readouts use binary units (KiB / MiB / GiB) and come from the compute_storage_stats Tauri command, which walks every workspace’s worktree directory concurrently on the blocking pool. The orphan scan uses scan_orphaned_worktrees, which only looks at the configured worktree_base_dir/<slug>/<wt_name>/ two-level layout — it does not scan arbitrary filesystem locations. Both run together on every Storage page mount and on Rescan.

Orphaned worktrees typically appear when:

• A user resets or deletes ~/.workbench/data.db but the worktree directories survive on disk.
• A dev sandbox under /tmp/workbench-dev/new-NNNN/ (from scripts/dev.sh --new) was kill -9’d before the cleanup trap could fire.
• Workspaces were imported on another machine and the SQLite DB diverged.

The per-orphan delete action only removes the directory itself — it does not touch the parent git repository or its .git/worktrees/ index, since orphan dirs are by definition no longer registered there. For worktrees still registered with a parent repo, use the per-row trash icon in the Existing worktrees found import dialog instead.

The cleanup modal shows live per-row progress while a run is in flight: a spinner next to pending rows, a green check as each row deletes, an X for failures, and a circled dash for rows the user cancelled. The Cancel button stays active during a run — clicking it (or closing the modal) signals cooperative cancellation, the in-flight row finishes, and every remaining row is skipped. Cancelled rows are untouched in the DB, so re-running cleanup picks them up.

Each row in the cleanup modal also shows the on-disk size of its worktree (binary units, sourced from the same compute_storage_stats scan the Storage page uses), and the selection counter renders a running “X B to free” total so the user can see the disk impact before confirming. Rows whose archive is still in flight — i.e. useWorkspaceLifecycle.archive flipped the store entry to Archived but the backend hasn’t yet committed the status flip — render disabled with a “still archiving” hint instead of letting the user click Delete and get a misleading “workspace no longer archived” failure. The modal re-runs the storage scan whenever the archived-id set in the store changes, so those rows become selectable as soon as the backend confirms.

The same modal is reachable from the project dashboard’s ARCHIVED section header and from each per-repo settings page’s Workspace cleanup field. See Bulk Cleanup of Archived Workspaces for the full UI walkthrough and the matching CLI subcommand.

Git

Setting	Description	Default
Branch prefix mode	How branches are prefixed: username, custom, or none	Username
Custom branch prefix	Prefix string when mode is custom	—
Auto-delete branch on archive	Delete local branch when archiving a workspace	—
Auto-fix CI failures	Create a new agent session when a workspace’s CI transitions from passing/running to failed. The session prompt includes failed checks and, when supported by the SCM provider, failed log output.	Off
CI auto-fix model	Model used for auto-fix sessions. Leave unset to use the global default model.	Use default model
CI auto-fix prompt template	Prompt template for the created session. Supports {{failed_checks}}, {{failure_logs}}, {{branch}}, {{pr_title}}, {{pr_url}}, {{pr_number}}, and {{all_checks}}.	Built-in template
CI auto-fix cooldown	Minimum seconds between auto-fix session creations per workspace. Values are clamped to 60-3600.	300 seconds
Show open issues & PRs in project view	Surface open issues and pull requests from the resolved SCM provider on the repo overview screen. Requires a configured SCM provider (scm-github, scm-gitlab). See Project view — Issues & PRs.	Off

Branch Prefix Mode

• Username — prefix with your git username (e.g., sean/add-health-check)
• Custom — use a custom prefix (e.g., feature/, fix/)
• None — no prefix, just the descriptive branch name

Auto-Delete on Archive

When enabled, archiving a workspace deletes the local branch — but only if the branch contains only checkpoint commits. If you’ve made manual commits on the branch, it will be preserved to prevent data loss.

CI Auto-Fix

When enabled, Workbench watches the SCM polling results for active workspaces. A new auto-fix session is created only after an observed transition to failed CI, not for a failure that was already present when polling first saw the workspace.

GitHub and GitLab providers attempt to include failed log output in the prompt. Providers that do not implement log fetching still create the session with failed check names and links.

Repository

Per-repository settings are documented in Per-Repo Settings.

Plugins

Setting	Description	Default
Built-in Workbench plugins	Toggle Rust-implemented Workbench tools such as file delivery.	Enabled
Voice providers	Choose and prepare voice input providers. If a provider cannot load in the current build, the row shows its own error while the rest of the Plugins panel stays usable.	Platform-dependent
Source control providers	Toggle bundled Lua SCM providers such as GitHub/GitLab.	Enabled
Environment providers	Toggle bundled Lua environment activators such as direnv, mise, dotenv, and Nix devshell.	Enabled
Env provider — Timeout (each env provider)	Maximum seconds to wait for a single env-provider invocation (direnv export, mise env, nix print-dev-env, etc.). Bumped from 30s to 120s in 0.24 — cold Nix flakes routinely run 60–120s. Range 5–600s.	120 seconds
Language grammars	Toggle bundled grammar plugins used by editor/chat highlighting.	Enabled
Reload bundled plugins	Reseed bundled plugin files from the app bundle, preserving user-modified plugin files.	—

Environment

Setting	Description	Default
Forwarded variables	Variables captured from your interactive shell that differ from the launch baseline. Masked by default; click Show values to reveal.	—
Inherited variables	Variables present in both your shell and the baseline with identical values (read-only reference).	—
Reload	Re-probe $SHELL and refresh the captured environment.	—
Disable shell env	Globally disable shell-env injection into agents and terminals. Other env providers are unaffected.	Off
User deny patterns	Glob patterns (one per line) for additional variables to exclude from forwarding, on top of the built-in denylist.	Empty

See Shell Environment Inheritance for the full feature guide.

Collaboration

Collaboration is always available. The Share button appears in the sidebar toolbar and the Collaboration section is always visible in Settings.

Setting	Description	Default
Display name	Name shown in the participants roster and on your messages in collaborative sessions. Leave empty to fall back to the OS hostname.	— (hostname)
Default plan consensus	Pre-check the “require unanimous plan approval” toggle in the share dialog.	Off
Require Tailscale network	When enabled, collaboration connections are only accepted from Tailscale IP addresses (100.x.y.z). Disable for LAN-only use.	On

See Collaboration for the full feature guide.

WakaTime

Setting	Description	Default
Enable WakaTime	Send heartbeats to WakaTime for activity tracking	Off
API Key	Fallback API key when ~/.wakatime.cfg is not present	—
API URL	Custom WakaTime API endpoint for self-hosted servers	https://api.wakatime.com/api/v1

See WakaTime for setup instructions and privacy details.

Help

Setting	Description
Version	Shows the installed Workbench version with a View changelog link to the matching GitHub release.
Keyboard shortcuts	Opens the keyboard shortcuts reference modal.
Documentation	Opens this documentation site.
Report an issue	Opens the GitHub issue tracker.
License & Legal	Opens a modal showing the Workbench license and upstream Claudette MIT attribution.

Environment Variables

Workbench sets the following WORKBENCH_* environment variables in every subprocess it spawns — terminals, setup and archive scripts, the agent CLI, and notification commands.

Variable	Description	Example
WORKBENCH_WORKSPACE_NAME	Workspace name	fix-auth-bug
WORKBENCH_WORKSPACE_ID	Workspace UUID	a1b2c3d4-...
WORKBENCH_WORKSPACE_PATH	Worktree absolute path	/Users/me/.workbench/workspaces/myrepo/fix-auth-bug
WORKBENCH_ROOT_PATH	Repository root path	/Users/me/code/myrepo
WORKBENCH_DEFAULT_BRANCH	Default branch name	main
WORKBENCH_BRANCH_NAME	Workspace branch name	sean/fix-auth-bug

These are useful in setup scripts, archive scripts, notification commands, and any tools you run in the integrated terminal.