pub struct Settings {Show 69 fields
pub auto_compact: bool,
pub auto_compact_threshold_percent: f64,
pub auto_compact_explicit: bool,
pub calm_mode: bool,
pub pet_mode: bool,
pub tool_collapse_mode: String,
pub low_motion: bool,
pub load_error: Option<String>,
pub fancy_animations: bool,
pub focus_texture: String,
pub work_surface_placement: String,
pub work_surface_top_height: u16,
pub work_surface_side_width: u16,
pub rail_panel: String,
pub constrained_frame_rate: bool,
pub bracketed_paste: bool,
pub paste_burst_detection: bool,
pub mention_menu_limit: usize,
pub mention_walk_depth: usize,
pub mention_menu_behavior: String,
pub show_thinking: bool,
pub thinking_default_expanded: bool,
pub thinking_preview_lines: usize,
pub thinking_highlight: bool,
pub help_expand_groups: bool,
pub contextual_tips: bool,
pub pin_last_prompt: bool,
pub show_tool_details: bool,
pub inline_diffs: String,
pub locale: String,
pub theme: String,
pub background_color: Option<String>,
pub composer_density: String,
pub composer_border: bool,
pub composer_multiline_mode: bool,
pub composer_vim_mode: String,
pub transcript_spacing: String,
pub default_mode: String,
pub sidebar_width_percent: u16,
pub sidebar_focus: String,
pub context_panel: bool,
pub sessions_rail: bool,
pub session_auto_resume: bool,
pub cost_currency: String,
pub max_input_history: usize,
pub default_provider: Option<String>,
pub default_model: Option<String>,
pub reasoning_effort: Option<String>,
pub permission_posture: Option<String>,
pub sandbox_mode: Option<String>,
pub provider_models: Option<HashMap<String, String>>,
pub enabled_models: Option<HashMap<String, Vec<String>>>,
pub pinned_models: Vec<PinnedModel>,
pub status_indicator: String,
pub synchronized_output: String,
pub workspace_follow_symlinks: bool,
pub feature_intro_shown: bool,
pub yolo_deprecation_shown: bool,
pub operate_deprecation_shown: bool,
pub account_preferences_notice_shown: Option<String>,
pub work_surface_bottom_migrated: bool,
pub behavioral_tip_impressions: BTreeMap<String, u8>,
pub dismissed_plugin_suggestions: BTreeSet<String>,
pub footer_hint_uses: BTreeMap<String, u8>,
pub agents: AgentSettings,
pub legacy_yolo_default: bool,
pub legacy_operate_default: bool,
pub tui_prefs_migration: Option<TuiPrefsMigration>,
pub provenance: BTreeMap<String, Layer>,
/* private fields */
}Fields§
§auto_compact: boolAuto-compact conversations when they approach the model limit.
auto_compact_threshold_percent: f64Context-window percentage that triggers pre-send auto-compaction when
auto_compact is enabled. The hard token floor still applies.
auto_compact_explicit: boolWhether the persisted settings file expressed an auto-compaction preference. Runtime defaults must not be written back as user intent when an unrelated setting is saved.
calm_mode: boolReduce status noise and collapse details more aggressively
pet_mode: boolUse the pet as the main view on the next launch.
tool_collapse_mode: StringDense tool-run collapse mode: compact, expanded, or calm.
low_motion: boolReduce decorative motion. This must never synthesize model text speed; streaming follows upstream deltas in both modes.
load_error: Option<String>Set when the persisted file existed but could not be parsed and the values above are defaults. Never serialized; surfaces must not present these defaults as saved.
fancy_animations: boolEnable expressive live-state motion. This affects chrome and state affordances only; model text always follows upstream stream deltas.
focus_texture: StringFocus-context texture prototype for modal views (#4823): off
(default), scrim dims the area outside the focused modal, grain
sprinkles deterministic dots over blank cells there. Static texture,
never obscures text; unknown values fall back to off at render time.
work_surface_placement: StringOcean Tasks / To-do / Workers rail placement: top, left, or right. The lower edge remains owned by the composer and phase footer.
work_surface_top_height: u16Remembered total height (content plus divider) for top Work placement.
work_surface_side_width: u16Remembered total width (content plus divider) for side Work placement.
rail_panel: StringWhich panel the rail shows: tasks, agents, context, or pinned.
Orthogonal to work_surface_placement (rail unification, 0.9.4).
constrained_frame_rate: boolRuntime-only 30 FPS cap for terminals that flicker at high redraw rates. Separate from accessibility motion and text delivery.
bracketed_paste: boolEnable terminal bracketed-paste mode. Default true. Disable if your
terminal mishandles the \e[?2004h escape (rare; some legacy
terminals over SSH+screen multiplex without the cap).
paste_burst_detection: boolEnable rapid-key paste-burst detection for terminals that do not emit
bracketed-paste events. Independent from bracketed_paste.
Maximum number of file-mention popup candidates retained before the composer renders its visible window. The widget paginates by terminal height, so this is a data-side cap rather than a visible-row budget.
mention_walk_depth: usizeMaximum workspace depth for @-mention completion walks. 0 means
unlimited depth; use with care in very large repositories.
@-mention completion behavior: fuzzy workspace search or deterministic
directory browser.
show_thinking: boolShow thinking blocks from the model
thinking_default_expanded: boolWhen true, thinking blocks render expanded by default instead of collapsed. Space still toggles collapse/expand. Useful for SSH/tmux users where the Space key may be captured by the terminal layer.
thinking_preview_lines: usizeCollapsed completed-thought preview rows. Default 2 (compact).
Set 10 for the older dump, or 0 for header-only. Full expand is
still thinking_default_expanded / Space.
thinking_highlight: boolKeep thinking visible while disabling its filled background treatment.
help_expand_groups: boolWhen true, Help/shortcuts groups start expanded. Default false folds the long tail. Type-to-filter still unfolds matches.
contextual_tips: boolShow quiet, action-triggered command discovery tips.
pin_last_prompt: boolPin the last user prompt at the top of the transcript when it has scrolled off. Default on.
show_tool_details: boolShow detailed tool output
inline_diffs: StringSuccessful structured File mutation evidence: full, summary, or off. This affects inline presentation only; exact evidence remains available through the tool-details route in every mode.
locale: StringUI locale: auto, en, ja, zh-Hans, zh-Hant, pt-BR, es-419, vi, ko,
ca, de, fr, id, hi, ru, uk.
Every shipped pack holds full en.json parity; nothing falls back.
theme: StringNamed UI theme. "underwater" is the fresh-install default: a dark
navy water column. "shoreline" is the warm charcoal alternative.
"terminal" fully inherits the
host terminal’s foreground/background. "system", "dark",
"light", "grayscale", and the community presets:
"catppuccin-mocha", "tokyo-night", "dracula",
"gruvbox-dark". The background_color setting still overrides the
surface color on top of the resolved theme.
background_color: Option<String>Optional main TUI background color as a 6-digit hex RGB value.
composer_density: StringComposer layout density: compact, comfortable, spacious
composer_border: boolShow a border around the composer input area
composer_multiline_mode: boolKeep bare Enter available for multiline drafting. When enabled, Alt+Enter and supported Shift+Enter submit; Ctrl+J remains a newline shortcut.
composer_vim_mode: StringComposer editing mode: “normal” (default) or “vim” for modal editing. When set to “vim” the composer starts in Normal mode; press i/a/o to enter Insert mode and Esc to return to Normal.
transcript_spacing: StringTranscript spacing rhythm: compact, comfortable, spacious
default_mode: StringDefault mode: “agent” (Work) or “plan”. Legacy permission shorthands are accepted for migration but never advertised as modes.
Legacy sidebar width as percentage of terminal width. Load-only
migration shim (0.9.4 rail unification): read by
migrate_sidebar_settings_to_rail, never written back.
Legacy sidebar focus mode: pinned, auto, tasks, agents, context, hidden. Load-only migration shim, never written back.
context_panel: boolEnable the session-context panel (#504). Shows working set, tokens, cost, MCP/LSP status, cycle count, and memory info.
sessions_rail: boolShow the persistent Sessions rail in the sidebar (#2934).
Off by default: the rail spends sidebar rows that Work, Activity, and Agents already compete for, so it is opt-in rather than something a user discovers by having their layout change under them.
session_auto_resume: boolReattach to this workspace’s most recent session on startup (#2934).
Off by default. --resume/--continue remain the explicit paths and
always take precedence; when this is on, startup still refuses to
resume an archived, unreadable, or foreign-workspace session and falls
back to a fresh transcript with a receipt. See
crate::session_resume for the decision table.
cost_currency: StringCost display currency: usd or cny.
max_input_history: usizeMaximum number of input history entries to save
default_provider: Option<String>Archived startup provider used only to migrate older settings into config.
default_model: Option<String>Archived DeepSeek fallback used only by the config selection migration.
reasoning_effort: Option<String>Default reasoning effort selected from the TUI model picker.
None falls back to config.toml and then the runtime default.
permission_posture: Option<String>TUI-only Shift+Tab posture: ask, auto-review, or full-access.
An explicit/managed config.toml approval policy always takes
precedence, so this preference cannot loosen project requirements.
This is tool-approval posture, not filesystem scope — see
Self::sandbox_mode.
sandbox_mode: Option<String>Filesystem sandbox scope, independent of approval posture:
read-only | workspace-write | danger-full-access | external-sandbox.
Surfaced in Settings and the shell so “Full Access” (approval) is
never confused with unrestricted filesystem writes.
provider_models: Option<HashMap<String, String>>Archived provider model choices used only by the config selection migration. Preserve them on unrelated settings saves until migrated.
enabled_models: Option<HashMap<String, Vec<String>>>Legacy additive picker list written by older builds on every model switch. Nothing reads it any more (#6533): the picker ranks by recent use instead. Parsed and preserved only so old files load and survive unrelated saves until a cleanup removes the table.
pinned_models: Vec<PinnedModel>Exact provider/model tuples pinned to the top of model choosers, in user-defined order. Stale entries remain persisted and visible.
status_indicator: StringHeader status indicator next to the effort chip. Cycles through a
per-turn animation keyed off App::turn_started_at:
"cw"(default): static typographic Codewhale mark."whale": historical🐳 → 🐋12-frame sequence originally shipped in v0.3.5, removed in v0.8.x’s “smoother TUI streaming” pass, restored in v0.8.30. Idle frame is a steady🐳."dots": the 6-frame geometric sequence (◍ ◉ ◌ ◌ ◉ ◍) that replaced the whale during the dots era."off": hide the indicator entirely.
synchronized_output: StringWhether to wrap each draw in DEC mode 2026 synchronized output
(\x1b[?2026h … \x1b[?2026l). Synchronized output asks the
terminal to defer rendering until the whole frame is staged so
GPU-accelerated terminals (Ghostty, VS Code, Kitty, WezTerm)
don’t flash a blank intermediate frame.
"auto"(default): emit DEC 2026 unless an environment signal says the active terminal mishandles it (currently Ptyxis 50.x on VTE 0.84.x — seeSettings::apply_env_overrides)."on": always emit DEC 2026 (override the auto opt-out)."off": never emit DEC 2026. Use this if your terminal flashes the whole screen on every redraw — most often Ptyxis on Ubuntu 26.04 today; historically also some legacy ssh+screen stacks. The cost ofoffis brief tearing on terminals that do support DEC 2026; it is purely a rendering-quality knob, not a correctness one.
workspace_follow_symlinks: boolFollow symbolic links during workspace file discovery walks (@-mention
completion, fuzzy resolve, and the file-index builder). When false
(default) symlinked directories are skipped, which keeps walks fast and
avoids accidentally traversing into system paths. Set to true to
support symlink-based multi-project workspaces where several project
directories are symlinked into a single hub directory.
Note: The walker has built-in cycle detection that skips already-
visited real paths, so symlink loops (A→B→A) will not cause infinite
recursion. However, enabling this on workspaces with symlinks that
point to large directory trees (e.g. /usr, home directories) can
significantly increase first-turn latency and memory usage.
feature_intro_shown: boolOne-time Fleet + Hotbar introduction has been shown. Drives a single
launch nudge (see App::maybe_show_feature_intro) so returning users
see it exactly once and never on subsequent launches.
yolo_deprecation_shown: boolOne-time YOLO deprecation toast has been shown. Suppresses the repeat toast after the first sighting per install (persisted across sessions).
operate_deprecation_shown: boolOne-time Operate-retirement toast has been shown. Same suppression
contract as yolo_deprecation_shown.
account_preferences_notice_shown: Option<String>§work_surface_bottom_migrated: boolRound 3 (2026-09-01) moved the work bar under the composer. Every
settings.toml saved before that carries work_surface_placement = "top" — the old default, persisted verbatim by ordinary saves, not a
choice anyone made. This flag records that the one-time top →
bottom migration ran, so a user who picks top afterwards keeps it.
behavioral_tip_impressions: BTreeMap<String, u8>Persisted impression counts for action-triggered, ephemeral product guidance. Keys are stable tip identifiers; values are bounded by the behavioral-tip engine and omitted entirely before the first sighting.
dismissed_plugin_suggestions: BTreeSet<String>Plugin names explicitly dismissed from proactive suggestions. Manual plugin commands remain available. Names are stored in lowercase.
Persisted use counts for the Tideline footer key hints. Keys are the
stable hint identifiers in crate::tui::footer_hints; a hint retires
to its bare state once its binding has been used enough times.
Omitted entirely before the first recorded use.
agents: AgentSettings§legacy_yolo_default: boolTrue only for the current load when default_mode = "yolo" was read
from an older settings file. App startup uses this provenance to migrate
the old bundled Full Access choice without weakening project or managed
approval policy. It is never written back to disk.
legacy_operate_default: boolTrue only for the current load when a retired default_mode = "operate" spelling was read. Never written back to disk.
tui_prefs_migration: Option<TuiPrefsMigration>Receipt for the one-time tui.toml fold performed by this load.
Never serialized: it describes what happened to a file, not a setting.
provenance: BTreeMap<String, Layer>Which layer supplied the in-force value of each schema key: user
config for keys settings.toml named at load, the default for the
rest, session for keys set() touched since. Runtime only — the
resolver reads it, disk never sees it. CLI flags (2D) and managed
policy / project producers mark their own layers when they land.
Implementations§
Source§impl Settings
impl Settings
Sourcepub fn path() -> Result<PathBuf>
pub fn path() -> Result<PathBuf>
Get the canonical settings file path.
New writes should target ~/.codewhale/settings.toml. Legacy
DeepSeek-branded paths remain readable as fallbacks during load, but we
no longer surface them as the primary path in /config.
Sourcepub fn load_read_only() -> Result<Self>
pub fn load_read_only() -> Result<Self>
Load settings for a diagnostic without migrating a legacy file.
This preserves the same candidate precedence, parser normalization, and
environment overlays as Settings::load. Unlike an interactive
startup, diagnostics must not create ~/.codewhale/settings.toml just
because they inspected a legacy ~/.deepseek/settings.toml file.
Sourcepub fn load_legacy_route_preferences_read_only() -> Result<Self>
pub fn load_legacy_route_preferences_read_only() -> Result<Self>
Read archived route preferences from the user-global settings store.
Canonical config migration must not inherit a project config’s sibling settings or runtime environment overlays, and must not migrate files.
Sourcepub fn load_persisted() -> Result<Self>
pub fn load_persisted() -> Result<Self>
Load the normalized values stored on disk without terminal/runtime overlays. Configuration editors use this path so a value labelled “saved” never silently reports a tmux, SSH, or accessibility override.
Sourcepub fn legacy_yolo_default_detected(&self) -> bool
pub fn legacy_yolo_default_detected(&self) -> bool
Whether this load normalized a legacy default_mode = "yolo" value.
This is migration provenance, not a user-facing mode. New writes accept only Agent or Plan and serialize the independent permission posture.
Sourcepub fn legacy_operate_default_detected(&self) -> bool
pub fn legacy_operate_default_detected(&self) -> bool
Whether this load read a retired default_mode = "operate" spelling.
Migration provenance only: the normalized value on disk is Work, and startup uses this to explain the change once instead of silently dropping the mode the user had saved.
Sourcepub fn tui_prefs_migration(&self) -> Option<&TuiPrefsMigration>
pub fn tui_prefs_migration(&self) -> Option<&TuiPrefsMigration>
Receipt for the one-time tui.toml fold, when this load performed one.
Sourcepub fn provenance(&self, key: &str) -> Layer
pub fn provenance(&self, key: &str) -> Layer
Which layer supplied the in-force value of key: the load ledger,
defaulting to Layer::Default for keys the document never named.
Aliases resolve to their canonical key first, so /set collapse
reports the same layer as the tool_collapse row.
Sourcepub fn value(&self, key: &str) -> Option<String>
pub fn value(&self, key: &str) -> Option<String>
The value key currently holds in this store, in its written-to-disk
string form — None when the key is not a field of this store.
Settings serializes field-for-field to settings.toml, so a document
lookup on the serialized form shares set’s key vocabulary instead
of growing a second hand-keyed reader beside it.
Sourcepub fn is_set(&self, key: &str) -> bool
pub fn is_set(&self, key: &str) -> bool
Whether the loaded settings document explicitly named key — a
persisted user choice rather than an inherited default.
Sourcepub fn auto_compact_explicitly_configured() -> bool
pub fn auto_compact_explicitly_configured() -> bool
Whether the user explicitly persisted an auto-compaction preference. A threshold is intent to enable compaction unless an explicit boolean says otherwise. When all three keys are absent, callers may choose a model-aware default.
Source§impl Settings
impl Settings
Sourcepub fn apply_env_overrides(&mut self)
pub fn apply_env_overrides(&mut self)
Apply environment-driven overlays after disk load. Used for
platform a11y signals that should ignore the user’s saved
preference (#450). The env values are consulted at startup;
changing them mid-session has no effect because settings are
only re-read on Settings::load().
Sourcepub fn transact<T>(mutate: impl FnOnce(&mut Self) -> Result<T>) -> Result<T>
pub fn transact<T>(mutate: impl FnOnce(&mut Self) -> Result<T>) -> Result<T>
Run one atomic load → mutate → save cycle against settings.toml.
Every writer that reads the whole file, changes some fields, and writes
the whole file back must go through here (or through
SettingsTransaction for the multi-step shape). save serializes the
complete struct, so two unsynchronized writers that each did their own
load_persisted will each write back the other’s pre-image: whichever
saves last silently reverts the other’s field. Locking save alone does
not help, because the stale read already happened before the lock.
Two locks are taken (see with_settings_transaction): a process-wide
mutex keyed by the resolved settings path, which covers writers that
never share an object — a background startup-default drain and a
synchronous Shift+Tab permission write, the concrete pair that lost
default_mode / permission_posture against each other — and a
cross-process file lock, which covers a second Codewhale process on the
same home directory.
The closure must not call transact, with_settings_transaction,
save, or load_persisted itself — the lock is not re-entrant. Use
with_settings_transaction when you need more than one save in one
critical section.
Sourcepub fn transact_opt<T>(
mutate: impl FnOnce(&mut Self) -> Result<Option<T>>,
) -> Result<Option<T>>
pub fn transact_opt<T>( mutate: impl FnOnce(&mut Self) -> Result<Option<T>>, ) -> Result<Option<T>>
Self::transact for a mutation that may decide there is nothing to
write. Returning None abandons the transaction without touching disk,
so a “flag already set” early return does not rewrite the file.
Sourcepub fn canonical_key(key: &str) -> Option<&'static str>
pub fn canonical_key(key: &str) -> Option<&'static str>
Set a single setting by key
Canonical schema key for a set() spelling: the first pattern of each
match arm below. None means set() rejects the spelling, so the
ledger never learns it. Keep in sync with the arms — the
set_marks_session_provenance test enforces it per spelling.
pub fn set(&mut self, key: &str, value: &str) -> Result<()>
Sourcepub fn apply_preset(&mut self, name: &str) -> Result<Vec<&'static str>>
pub fn apply_preset(&mut self, name: &str) -> Result<Vec<&'static str>>
Apply a named settings preset (#3478).
Presets are the first bundled-settings mechanism: a single name applies a
coherent group of presentation knobs. calm is the “beautiful/calm
transcript” preset — it quiets motion and verbose tool output while
keeping evidence reachable: thinking stays visible and tool runs stay
expandable (only their inline detail is collapsed), so maintainer/release
work is never blind to failures. Presentation only — no model, provider,
routing, or safety setting is touched. Reuses Settings::set so each
field goes through the same validation as a single-key set.
Returns the keys changed, or an error for an unknown preset.
Sourcepub fn command_report(&self) -> CommandSettingsReport
pub fn command_report(&self) -> CommandSettingsReport
Typed /settings text report: the command owns the frame and joining.
Sourcepub fn toggle_pinned_model(&mut self, provider: &str, model: &str) -> bool
pub fn toggle_pinned_model(&mut self, provider: &str, model: &str) -> bool
Toggle one exact provider/model pin without touching credentials or the provider’s default route.
pub fn move_pinned_model( &mut self, provider: &str, model: &str, delta: isize, ) -> bool
Sourcepub fn synchronized_output_enabled(&self) -> bool
pub fn synchronized_output_enabled(&self) -> bool
Resolved boolean for whether the renderer should wrap each frame in
DEC mode 2026 synchronized output. auto and on enable; off
disables. The auto → off flip for known-bad terminals happens
earlier in Self::apply_env_overrides; this method only inspects
the final state.
Sourcepub fn effective_bracketed_paste(&self) -> bool
pub fn effective_bracketed_paste(&self) -> bool
Runtime bracketed-paste mode after terminal-host quirks are applied.
This deliberately does not mutate Settings::bracketed_paste:
apply_env_overrides() can run before saving settings, and a legacy
conhost runtime fallback must not permanently disable bracketed paste
when the same config is later used in Windows Terminal or another
modern terminal.
Trait Implementations§
Source§impl<'de> Deserialize<'de> for Settings
impl<'de> Deserialize<'de> for Settings
Source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
Auto Trait Implementations§
impl Forget for Settings
impl Freeze for Settings
impl Move for Settings
impl RefUnwindSafe for Settings
impl Send for Settings
impl Sync for Settings
impl Unpin for Settings
impl UnsafeUnpin for Settings
impl UnwindSafe for Settings
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> DeserializeOwned for Twhere
T: for<'de> Deserialize<'de>,
Source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
Source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can
then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.Source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be
further downcast into Rc<ConcreteType> where ConcreteType implements Trait.Source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &Any’s vtable from &Trait’s.Source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.