Settings
Open settings with ⌘/Ctrl + , or from the sidebar. Settings are organized into sections.
General
Section titled “General”| Setting | Description | Default |
|---|---|---|
| Worktree base directory | Directory where new workspaces are created | ~/.claudette/workspaces |
| 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 |
| System tray | Enable/disable system tray integration | Enabled |
| Archive on merge | Automatically archive a workspace when its pull request is merged. See SCM Providers. | Off |
| 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 and streams progress back into Claudette. Used by chat and Usage-panel auth failures. | — |
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.6 1M, Opus 4.6, Sonnet 4.6, Haiku 4.5) | — |
| Default effort | Reasoning effort level (auto, low, medium, high, max) | Auto |
| Default thinking | Enable extended thinking blocks | Off |
| Show thinking blocks | Display thinking blocks in the chat UI | Off |
| Default plan mode | Start new sessions in plan mode | Off |
| Default fast mode | Start new sessions in fast mode | Off |
See Agent Configuration for detailed descriptions of each option.
Appearance
Section titled “Appearance”| Setting | Description | Default |
|---|---|---|
| Theme | Color theme (12 built-in + custom) | Default Dark |
| 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–24px) | 11px |
See Theming for details on built-in themes and creating custom themes.
Notifications
Section titled “Notifications”| Setting | Description | Default |
|---|---|---|
| Notification sound | Sound played when an agent needs input or finishes | Default |
| Notification command | Custom shell command to run on notification | — |
Notification Sound
Section titled “Notification Sound”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 to disable notification sounds.
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) |
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. 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 for the full pipeline (where logs go, JSON output, per-domain RUST_LOG filtering, multi-instance behavior, bug-report workflow).
| 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 | — |
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.
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. | — |
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.