Settings
Open settings with ⌘/Ctrl + , or from the sidebar. Settings are organized into sections.
General
Section titled “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 Nightly. Opting into Nightly is gated behind a confirmation dialog. Locked while an install is downloading or queued. | Stable |
| Worktree base directory | Directory where new workspaces are created | ~/.claudette/workspaces |
| Archive on merge | Automatically archive a workspace when its pull request is merged. See SCM Providers. | Off |
| Claudette 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 |
| Tray icon style | Tray icon rendering: Auto, Light, Dark, or Color. Disabled when the system tray is off. | Auto |
| Language | UI language: English, Spanish, Brazilian Portuguese, Japanese, Simplified Chinese, or German. See Internationalization. | English |
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). Claudette 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
Section titled “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 4.6, Sonnet 4.6 1M, Haiku 4.5; older models such as Opus 4.7 / 4.6 / 4.5 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 Claudette 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, LM Studio, OpenAI API, and custom providers in Settings > Models and the chat model picker. Codex, Ollama, and LM Studio 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 |
| Pi | Show the built-in Pi SDK harness. Refreshes models through Pi’s ModelRegistry; provider auth is configurable inline (see Pi providers row). | On |
| Pi providers | Inline list of providers Pi can talk to (Copilot via OAuth, OpenRouter/OpenAI/Anthropic/etc. via API keys). API-key dialogs default to writing ~/.pi/agent/auth.json (shared with terminal pi); a “Keep this key private to Claudette” checkbox switches to keychain-only storage under bucket piProviderSecrets. OAuth flows run a device-code modal in-app. Pi-default visible providers: GitHub Copilot, OpenRouter, OpenAI, Anthropic, Google Gemini, DeepSeek. | Per provider |
| 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 Claudette, 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, Pi, Ollama, LM Studio, and OpenAI API. | Provider-specific |
| Runtime (per backend card) | Which harness Claudette spawns for this backend: Pi (Claudette’s bundled Pi sidecar), Claude CLI (Claude Code subprocess with ANTHROPIC_BASE_URL / gateway env), or Codex app-server. Only renders on cards whose kind has more than one valid harness — Ollama / LM Studio default to Pi, Codex Native defaults to the Codex app-server, OpenAI cards default to Claude CLI. Selecting the default value clears the override so future default-policy changes pick the user back up. | Kind-specific |
See Agent Configuration for detailed descriptions of each option.
Experimental
Section titled “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 / Pi / Ollama / LM Studio 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 and Community 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
Section titled “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 Claudette 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 Claudette MCP bridge, and scripts can manage them with claudette routine. | On |
Claude CLI Flags
Section titled “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. Claudette’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
Section titled “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 (12 built-in + custom). | Default Dark |
| 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 |
| 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
Section titled “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 |
| Setting | Description | Default |
|---|---|---|
| Install CLI on PATH | Installs (or reinstalls / updates / uninstalls) the bundled claudette 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 claudette command can do.
Pinned Prompts
Section titled “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
Section titled “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 |
| Notification command | Custom shell command to run on notification | — |
Notification Sound
Section titled “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
Section titled “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\": \"Claudette: $CLAUDETTE_WORKSPACE_NAME needs attention\"}"Editor
Section titled “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
Section titled “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
Section titled “Diagnostics”| Setting | Description | Default |
|---|---|---|
| Log level | File-log filter applied when RUST_LOG is unset. Bare levels are scoped to Claudette’s crates so dependencies stay below debug/trace, with mdns_sd capped at warn. Restart required for changes to take effect. | default (info,claudette=debug,claudette_tauri=debug,claudette_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 ~/.claudette/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
Section titled “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
~/.claudette/data.dbbut the worktree directories survive on disk. - A dev sandbox under
/tmp/claudette-dev/new-NNNN/(fromscripts/dev.sh --new) waskill -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.
| 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
Section titled “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
Section titled “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
Section titled “CI Auto-Fix”When enabled, Claudette 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
Section titled “Repository”Per-repository settings are documented in Per-Repo Settings.
Plugins
Section titled “Plugins”| Setting | Description | Default |
|---|---|---|
| Built-in Claudette plugins | Toggle Rust-implemented Claudette 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. | — |
| Setting | Description |
|---|---|
| Version | Shows the installed Claudette 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. |
Environment Variables
Section titled “Environment Variables”Claudette sets the following CLAUDETTE_* environment variables in every subprocess it spawns — terminals, setup and archive scripts, the agent CLI, and notification commands.
| Variable | Description | Example |
|---|---|---|
CLAUDETTE_WORKSPACE_NAME | Workspace name | fix-auth-bug |
CLAUDETTE_WORKSPACE_ID | Workspace UUID | a1b2c3d4-... |
CLAUDETTE_WORKSPACE_PATH | Worktree absolute path | /Users/me/.claudette/workspaces/myrepo/fix-auth-bug |
CLAUDETTE_ROOT_PATH | Repository root path | /Users/me/code/myrepo |
CLAUDETTE_DEFAULT_BRANCH | Default branch name | main |
CLAUDETTE_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.
Shell environment
Section titled “Shell environment”The Shell environment card shows env vars Claudette captured from your interactive shell init (.zshrc, .bashrc, .zprofile, etc.). See Shell environment for the full feature page.
| Setting | Description | Default |
|---|---|---|
| Reload | Re-probes $SHELL immediately, picking up any rc-file changes. | — |
| Show / Hide (per row) | Toggle reveal of a captured variable’s value. Values are masked by default. | Masked |
| Additional deny patterns | Newline-separated glob list. Names matching any pattern are not forwarded to subprocesses. | empty |
| Disable shell-env entirely | Stops forwarding any captured shell vars. Per-project env-providers (direnv, mise, etc.) continue to work. | Off |