Settings

Claude Code Rust has a fullscreen settings surface with multiple tabs. These slash commands open that surface directly:

The settings surface is session-aware. Settings load when the app’s session starts, and some tabs need an active session before they can show live data.

Opening and navigating

Every command in the table above opens the same fullscreen surface on a different starting tab. The tab order is:

Settings -> Plugins -> Status -> Usage -> MCP -> Help

Tab moves to the next tab and Shift+Tab to the previous one. Esc closes the surface. Enter closes it as well wherever the selected item has no action of its own. The hint line at the bottom of the surface shows what Enter and Esc do at the current position. Each tab also has its own keys: the Plugins tab navigates plugin lists, the MCP tab opens server actions and authorization flows, the Status tab renames the session with r or generates a title with g, and the Usage tab refreshes with r.

Settings panes

The Settings tab has a second row with six panes: General, Memory, Permissions, Sandbox, Hooks, and Workflows & Worktrees. Each pane is one alphabetical list. Focus moves between three areas stacked from top to bottom: the pane row, the search field, and the list.

Each pane remembers its own selection. Switching to another top-level tab and back keeps the pane, selection and search.

Below 30 columns or 12 rows the surface asks you to resize the window instead of drawing an unusable layout.

Search

Press / to search the current pane. A setting matches when its label, description or setting ID contains every word you typed, ignoring case. Search covers only the current pane and never looks inside saved values such as hook commands, credential entries or environment values.

Switching panes clears the search.

Help

Use /help when you want fullscreen help inside the same tabbed surface. The Help tab has three sections:

Use Left and Right inside the Help tab to switch sections. Use Up and Down to move through rows in the active section.

The Help tab is live UI, not a static manual page. Its Shortcuts section changes with focus and state, and its Commands and Subagents sections depend on what the active SDK session advertises.

Where settings are saved

Each save goes to one scope. Press s in the list to cycle the save scope through User, Project and Local.

Not every setting can be saved at every scope. A setting that the selected scope cannot hold is read-only until you switch scope; Settings by pane lists the restrictions.

Workspace trust is recorded separately in ~/.claude.json. It is not a settings scope and is never used as a fallback for a setting.

Set CLAUDE_CONFIG_DIR before startup to use an isolated Claude profile. User settings then live in <directory>/settings.json, workspace trust in <directory>/.claude.json, and file credentials in <directory>/.credentials.json. Sessions, plugins and authentication use the same directory. Project and Local settings stay in the project, and app preferences and diagnostics keep their normal OS locations.

Set CLAUDE_RS_CONFIG_DIR to select a separate directory for this app’s preferences. They are read from and saved to <directory>/settings.json, including the footer layout, presentation preferences, notification categories and update preferences. An empty or unset value uses the normal OS config location. This override is independent of CLAUDE_CONFIG_DIR; diagnostics retain their normal location.

The Settings tab shows saved values. A running session can differ, because workspace trust, managed policy, model capabilities, startup arguments and session commands also apply. The Status tab and the chat footer show what the session is running with.

Reading the list

Each row shows a setting and its value, and a counter such as 1/27 shows the position in the pane. Below the list, Description: explains the selected setting and a context line states where its value comes from at the selected scope:

Default means that no scope sets a value. It does not say whether the built-in behavior is On or Off; where the built-in behavior is known, the description states it, for example Default: On.

Read-only restrictions and settings-file errors appear as warnings below the description.

Claude decides which settings files it loads: some invalid entries are ignored individually, while other schema errors exclude the whole file. Not loaded reports that outcome without naming the cause. Saving and resetting still work on any readable file, and correcting the offending value restores loading.

Editing a value

Changes made with Left, Right or Space are saved as you make them, so closing with Enter or Esc discards nothing.

The text editor used for settings such as Language takes Enter to save, Ctrl+R to reset and Esc to cancel.

Reset removes the value saved at the selected scope. The row then shows the value from another scope, or Default. Reset does not write a replacement value and does not restore an earlier edit.

While a save is in progress the row keeps showing the last confirmed value. A successful save shows Saved.

Saving a default never changes the running session. Use /model, /mode, /effort, /thinking, /agent, /fast or /ultracode for the current session; see Session Commands.

Lists and structured settings

Permission rules, directory and domain lists, hook definitions and the structured sandbox settings open an editor instead of changing in place. The row in the main list shows how many entries are saved at the selected scope.

The editor loads only the entries saved at the selected scope, not a merged view of all scopes, and keeps that scope until it closes.

While typing in a field:

Rules for these structured editors:

• Edits stay in a draft until Ctrl+S. Accepting a field does not write the file.
• Many lists merge across scopes. Removing the last entry saves an explicit empty list, and entries from other scopes still apply. Reset removes the setting from this scope instead.
• Invalid JSON or a value that Claude rejects keeps the draft open for correction. Nothing is written.
• If the file changed on disk while the editor was open, the editor loads the latest version and keeps your draft. Save again to confirm.
• If the session moves to another project while an editor is open, saving is blocked. Close the editor and open it again.
• A scope that cannot be edited can still be opened for inspection.
• Opening, browsing and validating never run hooks or credential helpers, and never read secret files or environment values. Header values and command arguments are redacted in summaries.
• Fields that the form does not know are preserved when you save.

Editing permission rules

In the Permissions pane, open Allow rules, Ask rules, Deny rules or Additional directories. Add one tool rule per entry, for example Bash(npm test *) or Read(./src/**). A deny rule wins over an allow rule from any scope.

Editing hooks

Hooks → Definitions shows a flat list with each hook’s event, matcher and action.

• a starts guided creation: choose an event, enter an optional matcher, choose an action, fill its required fields, then review. Enter on the review step adds the hook to the draft and opens its optional fields. Esc goes back one step and cancels at the first step.
• Enter edits the selected hook.
• m edits the matcher of the hook’s group. Every hook in that group shares the matcher.
• Delete removes only the selected hook.

Hook actions are command, prompt, agent, HTTP and MCP tool. Event names come from the installed SDK. The JSON view shows the same definitions in the settings-file format:

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        { "type": "command", "command": "echo Check shell operation", "timeout": 10 }
      ]
    }
  ]
}

Saving replaces the hooks object at the selected scope. Hooks from other scopes keep merging in. Disable all is a separate On/Off setting.

Command and HTTP actions offer Failure policy (onFailure): continue reports a failed hook and lets the guarded action proceed; block treats the failure as exit code 2. Failures include startup errors, timeouts, exit codes other than 0 or 2, and invalid JSON or JSON that does not match the hook schema. Unset uses continue. Select the field and press Delete to remove only that handler’s override, then Ctrl+S to save.

The SDK ignores this policy for asynchronous hooks and the Stop, SubagentStop, TaskCompleted and TeammateIdle events. It decides whether an event can block an action. Editing or validating the policy never executes a hook.

Editing sandbox settings

Path, domain and command lists use the list editor. Credential protection, TLS termination, Ignored violations and Ripgrep command open forms:

• Required fields are marked with *.
• Fixed choices open a picker.
• Credential entries take file paths and variable names, never secret values.
• TLS termination takes both a CA certificate path and a CA key path, or neither.
• Proxy ports accept whole numbers from 1 to 65535.

Settings by pane

Every row has a description in the app. This section covers behavior that needs more explanation. Unless noted, a setting can be saved at User, Project or Local scope and applies to new sessions.

General

General also holds the settings described under Presentation and scrolling, Notifications and Automatic updates.

Default effort belongs to the saved Default model and is saved per model, so changing Default model switches the effort row to the new model. max is available only through /effort in a session. The row is read-only when the default model is unknown or offers no effort levels. Environment settings, workspace trust and organization caps can still change the effort a session runs with; the chat footer shows the applied level.

Question timeout submits a waiting question after the chosen idle time. Only answers you explicitly selected are sent, together with any notes; untouched questions are skipped. Keyboard, paste and mouse activity restart the interval, and the timer pauses while another screen has focus. Never waits for confirmation.

Dialog expiry cancels forwarded remote dialogs and held cross-session messages after the chosen time. Local permission prompts get no deadline. Reset restores 5 minutes. The CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS environment variable takes precedence.

Memory

Idle compaction follows the SDK’s settings cascade. Reset removes the preference at the selected scope and exposes the remaining scope or Default. Its saved On/Off value is a preference, not evidence that idle compaction is available or running; availability remains under SDK control.

Permissions

Sandbox

The Sandbox pane covers sandbox execution, filesystem paths, network domains, proxy ports and credential protection under the sandbox. key. Descriptions name the settings that apply to one platform only. Workspace trust, platform support and organization restrictions decide which saved values take effect, and can make rules and allowlists read-only.

These settings are User only: Disable filesystem isolation, Strict domain allowlist, TLS termination, Credential protection, Allow Apple Events and Ripgrep command.

Hooks

Workflows & Worktrees

Unavailable settings

Continue at usage limit and Messages from other sessions are listed in General but are read-only in this version. Themes and Vim editor mode are not offered.

Presentation and scrolling

These General settings apply immediately, including to the conversation already on screen.

The first five are Claude settings and can be saved at User, Project or Local scope. The last two are app preferences and are always saved for the user.

Timestamps and durations. When Claude supplies no timestamp, a live message shows the locally observed time marked (observed); resumed messages without a timestamp stay unstamped. With both settings On, the duration row also shows the completion time (Done). When the SDK reports no turn timing, a live response shows an Observed duration. Tool progress time is a lower bound, shown with ≥, and task time is labelled separately; neither is added to the turn total. Resumed responses show a duration only when the session history contains one.

Time format. Auto follows the system locale. 12-hour shows AM/PM and 24-hour UTC adds a Z suffix. A custom strftime pattern written into a settings file is used and preserved; the picker offers only the four presets. A timeZone entry in a settings file, such as Europe/Berlin, sets the zone for local presets and custom patterns. An unknown zone name falls back to the system zone.

Scrolling. Page Up pauses following and reads earlier output; Page Down reads later output. Ctrl+End jumps to the latest output and resumes following when Auto-scroll is On. With Auto-scroll Off it jumps once and then holds that position. The reading position survives new output and window resizing. The mouse wheel belongs to the terminal’s own scrollback unless the terminal forwards mouse events to the app.

Footer

Open /config → General → Footer with Enter or Space. The chat footer uses one row with independently ordered left- and right-aligned groups. Changes save automatically, and the running footer changes after each successful save. Layout and colors load before the first frame and remain available while connecting or authenticating. You can edit the footer when authentication is required, before an agent session exists. The field-position counter appears in the dialog’s top-right corner. The settings row shows Default layout until a layout is saved, then Custom layout.

You can keep editing while a save is in progress. Later edits are saved next, using the confirmed file revision. A failed save or conflict keeps your edits in the dialog and shows an error; Enter retries the save, and Esc discards the unsaved edits and closes. Session changes leave the active footer, editor draft, and local saves intact.

Model, effort, working directory, Git branch, and context remaining support optional colors. Press C to expand a palette directly below the selected field. Arrow keys move between color boxes; the selected color name appears underneath. Enter applies and autosaves the choice, while Esc or C collapses the palette without applying it. Choose Current (Home) to restore the field’s existing appearance. Permission mode, Fast mode, and Ultracode retain their fixed colors. Narrow windows show fewer boxes per row and keep the focused box visible.

Permission mode, model, effort, Ultracode, fast mode, running subagents, working directory, Git branch and context remaining are independent fields. Hiding the model does not hide effort or Ultracode; hiding the directory does not hide the branch. Fields appear only when their session data applies: effort requires a model that supports it, Ultracode requires verified effective state, running subagents requires at least one non-ambient subagent of the current session still running (one count per task across resumes, including stopping requests; see /agents), and branch requires a Git branch.

Permission and startup MCP-authentication notices remain at the far right and take priority over configured fields. On narrow terminals, paths and branches shorten first, then later fields are omitted, with the left group preceding the right group for overflow priority. The footer never wraps.

The layout is a user-level app preference saved as the presentation.footer array in the app-preferences file described under Where settings are saved. Each entry has an id, a visible boolean, a side of left or right, and an optional color; array order determines reading order within each group. The field IDs are permissionMode, model, effort, ultracode, fastMode, runningSubagents, directory, gitBranch and contextRemaining. Omitted fields remain available in the dialog but are hidden. An empty array hides all optional fields. Removing the setting restores the built-in layout.

For example, { "id": "model", "visible": true, "side": "left", "color": "cyan" } sets the model color. Omitting color keeps its existing appearance. The palette IDs are red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, white, gray, and slate.

Notifications

Notifications alert only while the terminal reports that it is unfocused. A terminal without focus reporting stays silent. These General settings apply immediately:

Notification method is a Claude setting saved for the user. The three category toggles are app preferences. They do not change the mobile-push settings inputNeededNotifEnabled and agentPushNotifEnabled.

Auto uses the terminal’s own notification protocol on iTerm2, Ghostty and Kitty, and otherwise sends a desktop notification with a terminal bell. A terminal-specific method uses its protocol on that terminal and falls back to a desktop notification elsewhere. iTerm2 with bell adds the bell, and Terminal bell sends only the bell. Desktop notifications can be unavailable over SSH. Protocol references: iTerm2, Ghostty, and Kitty.

Two limits apply to every method:

• Ordinary notices from Claude, including high-priority ones, appear in the transcript and do not raise an alert.
• An alert is sent when its event happens or not at all. Resuming a session, regaining focus or changing a setting never delivers earlier alerts.

If Claude already delivered a requested alert on this machine, the app does not send a second one. A mobile push alone does not suppress the local alert.

To investigate a missing alert, see Notification diagnostics.

Automatic updates

Automatic updates is an app preference saved as updates.autoInstall. It defaults to Off.

Update checks run in both modes and are cached for 24 hours. --no-update-check and CLAUDE_RUST_NO_UPDATE_CHECK disable checking and therefore automatic installation.

Automatic installation is skipped for source builds and unrecognized installations, after a forced shutdown, and after an application error. The setting is read again at exit, so switching it Off during a session cancels the pending installation.

The installation runs detached from the terminal and asks no questions. On exit the app prints one line naming the version and returns to the shell; closing the terminal does not stop the installation. Only one background installation runs at a time, and one that takes longer than 10 minutes is stopped.

Installer output is written to claude-rs-update.log in the parent of the runtime log directory, replacing the log of the previous installation. A failed installation is shown as a warning at the next start and retried after the next normal exit.

The setting updates only claude-rs. It does not update a separately installed Claude CLI.

How files are changed

• A save changes only the key of the edited setting. Other keys, unknown keys and values the app does not understand are left as they are.
• Reset removes the key and any parent object that becomes empty. It never writes a substitute default.
• A missing settings file is created on the first save.
• A file that contains invalid JSON, is not a JSON object, cannot be read, or is a symlink is blocked from editing. The app does not repair, replace or back up such a file.
• Saving at Local scope inside a Git repository adds .claude/settings.local.json to the repository’s private .git/info/exclude when needed. A Local settings file that Git already tracks is rejected.
• Only the edited setting is validated. An unrelated invalid value elsewhere in the file does not block the save, but it can still prevent Claude from loading the file; see Not loaded under Reading the list.
• A change made to the same setting by another program is detected before writing. The app reloads and keeps your draft. An editor that writes at the same instant without honoring the app’s lock file can still overwrite a save.

Offline inspection

These read-only commands inspect redacted settings files without starting the TUI:

claude-rs config
claude-rs config show --which project-settings
claude-rs config export --output claude-rs-config.json

The output covers User, Project and Local settings and the preferences file. Malformed files are reported, not rewritten. The commands read the files as they are on disk: they do not combine scopes and do not include managed policy. See Config Inspection.

MCP

The MCP tab shows live session-backed MCP state. Use /mcp to inspect servers, refresh status, complete authorization, reconnect servers, and handle SDK-provided MCP prompts when available.

If no session is active, the tab asks you to open or resume a session first. If the active session reports no MCP servers, the tab shows an empty state rather than editing raw config files.

MCP input requests open a dialog over this tab. Supported forms edit strings, numbers, whole numbers, booleans, single choices, and arrays of string choices, including titled choices and defaults. Required fields and supported length, numeric range, choice-count and date/email/URI/date-time constraints are validated before Accept. false and 0 are answers. Optional fields start omitted unless the server supplies a default; Ctrl+O includes or omits the focused optional field, so an included empty string differs from omission. Unsupported schemas show a reason and allow Decline or Cancel without offering Accept.

Use Tab/Shift+Tab or Up/Down to move between fields and actions. Type or paste into text and numeric fields, use Left/Right for choices, and Space to toggle a boolean or the highlighted multi-choice option. Enter advances from a field or activates the selected action. Ctrl+Enter accepts when the terminal distinguishes it; navigating to Accept works in every terminal. Esc cancels. A validation or send error retains the draft for correction or retry.

Overlapping requests wait in arrival order; the dialog shows the waiting count. A new request does not replace the form being edited. Only the active URL request opens a browser. SDK cancellation removes its matching request, including one still queued. A submitted dialog stays pending until its SDK callback settles, and prevents duplicate submission. Drafts remain in memory for the active session and are discarded on settlement or session teardown; form answers are not written as settings or diagnostic fields.

Plugins

The Plugins tab is available through /plugins. It shows installed plugins, marketplace plugins, configured marketplaces, and Session attachments.

Supported actions include enabling, disabling, updating, uninstalling, and installing plugins into user, project, or local scopes when those actions are available for the selected plugin.

After plugin changes, the app requests a session runtime plugin reload when an active session is available.

In the Session list, choose Load local folder or press l outside search. Enter the plugin directory, using an absolute path or a path relative to the session’s working directory. The SDK loads it into the current session without installing it into a persistent scope or changing marketplaces. Confirmed folders show Source: Session, their folder, and the SDK’s source and version when supplied. Select an existing folder and press Enter to load it again after editing its files; r reloads the current inventory.

A reload that would invalidate the prompt cache opens an Apply/Decline confirmation. Until Apply, no requested folder is added. Apply submits the same folders; declining keeps the draft and the session’s existing plugins. A rejected request keeps the draft for retry. A reload can apply with component errors: the app shows the SDK’s error count and reconciles the confirmed plugins, commands, agents and MCP servers. A host reconciliation failure is reported separately and does not imply that the attachment was rolled back.

Confirmed attachments are retained when the bridge replaces or resumes the same active session, including rewind. They are not persisted by the host: after restarting the app or switching away and returning, load the folders again. A fresh session does not inherit them. Before the first prompt after a replacement, press r in Session to obtain a new SDK inventory if it is not yet listed. Managed policy, remote environments or an already-running sandbox can reject local folder loading; the SDK’s refusal is shown without a persistent-install fallback.