---
title: Settings
description: Complete reference for all Claudette 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 **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](/claudette/features/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, or Simplified Chinese. See [Internationalization](/claudette/features/internationalization/). | English |

## 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). 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

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.7 1M, Opus 4.7, Sonnet 4.6, Sonnet 4.6 1M, Haiku 4.5; older models such as Opus 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](/claudette/features/agent-configuration/) for detailed descriptions of each option.

## 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](/claudette/features/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](/claudette/features/agent-scheduling/). The current surface is CLI and agent-tool driven; scheduled rows persist in the app database and re-arm when Claudette starts.

| 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

| 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](/claudette/features/per-repo-settings/#claude-cli-flag-overrides).

See [Agent Configuration → Claude CLI Flags](/claudette/features/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 (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](/claudette/features/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](/claudette/features/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 `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](/claudette/features/cli-client/) for what the `claudette` command can do.

## Pinned Prompts

Manage global [pinned prompts](/claudette/features/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 |
| 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](#environment-variables) are available, so your script can identify which workspace triggered the notification.

**Example** — send a Slack message:

```bash
curl -X POST "$SLACK_WEBHOOK_URL" \
  -d "{\"text\": \"Claudette: $CLAUDETTE_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](/claudette/features/diff-viewer/)). | 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. Restart required for changes to take effect. | `default` (`info,claudette=debug,claudette_tauri=debug,claudette_server=debug`) |
| 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](/claudette/features/diagnostics/) 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 `~/.claudette/data.db` but the worktree directories survive on disk.
- A dev sandbox under `/tmp/claudette-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](/claudette/features/git-worktrees/#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](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, 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

Per-repository settings are documented in [Per-Repo Settings](/claudette/features/per-repo-settings/).

## 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. | — |

## Help

| 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

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](/claudette/features/per-repo-settings/#setup-script), [archive scripts](/claudette/features/per-repo-settings/#archive-script), [notification commands](#notification-command), and any tools you run in the [integrated terminal](/claudette/features/integrated-terminal/).
