Struct Settings 

pub struct Settings {

    pub version: u32,
    pub thinking_level: ThinkingLevel,
    pub theme: String,
    pub glyph_set: GlyphSet,
    pub default_model: Option<String>,
    pub default_provider: Option<String>,
    pub last_used_model: Option<String>,
    pub last_used_provider: Option<String>,
    pub max_tokens: Option<u32>,
    pub temperature: Option<f32>,
    pub default_temperature: Option<f64>,
    pub max_response_tokens: Option<usize>,
    pub session_history_size: usize,
    pub session_dir: Option<PathBuf>,
    pub extensions_enabled: bool,
    pub auto_compaction: bool,
    pub disabled_tools: Vec<String>,
    pub tool_timeout_seconds: u64,
    pub ask_timeout_secs: u64,
    pub extensions: Vec<String>,
    pub skills: Vec<String>,
    pub prompts: Vec<String>,
    pub themes: Vec<String>,
    pub custom_providers: Vec<CustomProvider>,
    pub dynamic_models: HashMap<String, Vec<String>>,
    pub keybindings: HashMap<String, Vec<String>>,
    pub edit_format: EditFormat,
    pub todo_panel_enabled: bool,
    pub todo_eager_mode: TodoEagerMode,
    pub todo_reminders_enabled: bool,
    pub todo_reminders_max: u32,
    pub todo_clear_delay_secs: i64,
    pub agent_hub_enabled: bool,
    pub snapcompact_enabled: bool,
    pub mermaid_render_enabled: bool,
    pub inline_images: bool,
    pub commit_tool_enabled: bool,
    pub bash_pty: bool,
    pub memory_enabled: bool,
    pub ttsr_enabled: bool,
    pub ttsr_interrupt_mode: String,
    pub model_roles: HashMap<String, String>,
    pub advisor: AdvisorSettings,
    pub hooks: Vec<HookSpec>,
}

Application settings

Fields

version: u32

Settings format version. Used for automatic migration.

thinking_level: ThinkingLevel

Thinking level for agent responses

theme: String

Color theme — resolved by oxicode_vtui::theme (e.g. “oxi”, “oxide-dark”, “nord”).

glyph_set: GlyphSet

Terminal glyph set — controls every UI symbol (status markers, list cursors, box drawing, spinners, icons).

unicode (default): box-drawing + emoji, works on any UTF-8 terminal. ascii: 7-bit fallback for serial consoles / CI logs. nerd: Nerd Font private-use codepoints (needs a patched font).

default_model: Option<String>

Deprecated: use last_used_model instead. Kept for serde backward compat.

default_provider: Option<String>

Deprecated: use last_used_provider instead. Kept for serde backward compat.

last_used_model: Option<String>

Model selected by the user (last used = current default). Set during onboarding and updated every time the user switches model.

last_used_provider: Option<String>

Provider for the last used model.

max_tokens: Option<u32>

Max tokens for responses

temperature: Option<f32>

Temperature for generation (0.0–2.0)

default_temperature: Option<f64>

Default temperature as f64 (higher precision, takes precedence over temperature)

max_response_tokens: Option<usize>

Maximum tokens for generation (usize variant, takes precedence over max_tokens)

session_history_size: usize

Session history size (entries to keep in memory)

session_dir: Option<PathBuf>

Directory for storing sessions (default: canonical home sessions/)

extensions_enabled: bool

Whether extensions are enabled

auto_compaction: bool

Whether to auto-compact conversations that exceed context window

disabled_tools: Vec<String>

Built-in tools to disable (by name, e.g. ["web_search", "github_search"]). All tools are enabled by default; list tools here to turn them off.

tool_timeout_seconds: u64

Timeout in seconds for tool execution

ask_timeout_secs: u64

Ask overlay timeout in seconds. 0 = disabled (wait indefinitely). When timeout fires, auto-selects the recommended option (or first).

extensions: Vec<String>

List of extension paths or npm package sources to load

skills: Vec<String>

List of skill paths or npm package sources to load

prompts: Vec<String>

List of prompt template paths to load

themes: Vec<String>

List of theme paths to load

custom_providers: Vec<CustomProvider>

Registered custom providers (loaded from [[custom_provider]] TOML sections).

dynamic_models: HashMap<String, Vec<String>>

Cached model lists fetched from provider /models endpoints. Key is the provider name, value is a list of model IDs. Updated when API keys are entered in setup wizard or on demand.

keybindings: HashMap<String, Vec<String>>

User-defined keybinding overrides. Format: { "ActionName": ["Ctrl+x", "Alt+y"] } Actions are matched case-insensitively. Declared here for config persistence; not currently consumed by the tui_vt host loop.

edit_format: EditFormat

Per-channel output language for the TUI agent loop.

Maps a channel key (e.g. "response", "code_comment", Edit format for the edit tool.

str_replace (default): traditional find-and-replace. hashline: line-anchored patches with content-derived tags.

todo_panel_enabled: bool

Enable the sticky todo panel in the TUI. Default: true.

todo_eager_mode: TodoEagerMode

How strongly to auto-create a todo list on the first turn. Default: off.

todo_reminders_enabled: bool

Remind the agent to finish open todos before it stops. Default: true.

todo_reminders_max: u32

Max stop-time todo reminders per run. Default: 3.

todo_clear_delay_secs: i64

Seconds after every todo closes before the HUD auto-clears. Default: 60; 0 = instant; negative disables clearing.

agent_hub_enabled: bool

Enable the Agent Hub overlay (Ctrl+h / /agents). Default: true.

snapcompact_enabled: bool

Enable the Snapcompact PNG-frame compactor. Default: false (experimental).

mermaid_render_enabled: bool

Enable Mermaid diagram rendering in markdown. Default: true.

inline_images: bool

Inline image previews in the TUI (kitty / iTerm2 graphics protocols). Kill-switch for terminals that misrender image escapes. Default: true.

commit_tool_enabled: bool

Enable the Commit tool with optional LLM analysis. Default: false (opt-in, LLM cost).

bash_pty: bool

Run the bash tool inside a real PTY so ANSI SGR color sequences survive in command output (F-9, audit 2026-08-24). Default: false.

Currently inert. The agent crate (oxicode-agent) cannot see cli settings today — ToolContext carries no settings field, and Settings::apply_env() is a no-op. The only live gate is the OXICODE_BASH_PTY=1 environment variable, which is checked directly in BashTool::execute. Setting bash_pty = true in your settings file is silently ignored and emits a one-time tracing::warn! at settings load. The field is reserved for the eventual cli→agent settings plumbing — once that ships, the setting will be respected automatically.

To opt in today: export OXICODE_BASH_PTY=1 in the environment before invoking oxicode.

memory_enabled: bool

Enable session-spanning memory tools (retain/recall/reflect/edit) backed by the oxibrain daemon — the Oxi Foundation host’s only durable-memory authority. Default: true. Machines without the daemon degrade honestly (tools return typed unavailable results).

ttsr_enabled: bool

Enable Time-Traveling Stream Rules (stream interrupt on rule violation). Default: false (opt-in, stable-first).

ttsr_interrupt_mode: String

TTSR interrupt mode. Default: “prose_only”.

model_roles: HashMap<String, String>

Named model-role → model-pattern assignments (e.g. "commit" → "anthropic/claude-haiku", "slow" → "pi/default").

Empty by default. Role names are open-ended: the 10 built-in roles (default/smol/slow/vision/plan/designer/commit/title/ task/advisor) plus any user-defined role are accepted. Resolution — including pi/<role> alias expansion with cycle detection — is done by oxicode_ai::RoleRegistry. The role-switching layer (which role is active when) is wired separately.

advisor: AdvisorSettings

Advisor subsystem settings. Default OFF (opt-in). Drives the oxicode_agent::advisor engine wired into AgentSession.

hooks: Vec<HookSpec>

User-configured event→shell-command hooks. Loaded from the [[hooks]] array in settings.toml. Project hooks are gated by the first-run approval (see store/hook_approval.rs).

Implementations

impl Settings

pub fn settings_dir() -> Result<PathBuf>

Get the global settings directory path (the canonical oxicode home: $OXICODE_HOME, else $OXI_HOME/oxicode, else ~/.oxi/oxicode).

pub fn settings_toml_path() -> Result<PathBuf>

Get the global settings TOML file path (<settings_dir>/settings.toml).

pub fn settings_json_path() -> Result<PathBuf>

Get the global settings JSON file path (<settings_dir>/settings.json).

pub fn settings_path() -> Result<PathBuf>

Get the global settings file path (JSON takes priority).

Returns the path to the settings file that should be used. If both JSON and TOML exist, JSON is returned (takes priority). If only one exists, that path is returned. If neither exists in the canonical home, falls back read-only to the legacy home (~/.oxicode/settings.{json,toml}) when present. Otherwise returns the canonical JSON path by default (the write target).

pub fn settings_path_with_preference(prefer_json: bool) -> Result<PathBuf>

Get the effective settings file path, preferring the specified format.

If prefer_json is true, checks JSON first; otherwise checks TOML first. Returns the first existing file, or — when the canonical home has neither — the legacy home’s file (read-only) when present. Falls back to the canonical preferred path otherwise.

pub fn detect_format(path: &Path) -> SettingsFormat

Detect the settings file format from its path.

pub fn find_project_settings(start_dir: &Path) -> Option<PathBuf>

Get the project-local settings file path.

Searches for .oxicode/settings.json first, then .oxicode/settings.toml. Returns the first one found, or None if neither exists.

pub fn effective_session_dir(&self) -> Result<PathBuf>

Resolve the effective session directory.

Priority: session_dir field → canonical home sessions/.

pub fn load() -> Result<Self>

Load settings, applying all layers:

1. Built-in defaults
2. Global canonical settings ($OXICODE_HOME, else ~/.oxi/oxicode/; legacy ~/.oxicode/ read-only fallback)
3. Project .oxicode/settings.toml
4. Environment variable overrides

Examples

use oxicode_cli::Settings;

let settings = Settings::load().expect("Failed to load settings");
println!("Using model: {}", settings.effective_model(None));

pub fn load_from(dir: &Path) -> Result<Self>

Load settings with an explicit working directory for project config discovery.

Always layers the global config from Self::settings_path() when it exists. Use Settings::load_from_with to inject a custom global path (e.g. for tests or portable mode).

pub fn load_from_with( dir: &Path, global_override: Option<&Path>, ) -> Result<Self>

Load settings with an explicit project directory and an optional global settings path override.

Layering order:

1. Defaults
2. Global config from global_override if Some, else from Self::settings_path() if it exists.
3. Project config (<dir>/.oxicode/settings.{toml,json}).
4. Environment variable overrides.
5. Migration.
6. TUI language policy validation.

Passing global_override = None keeps the default behavior of reading the user’s real global settings (canonical home, with legacy read-only fallback). Tests pass Some(custom_path) or rely on the real path being absent to get pure defaults. (The test suite uses Some(specific_path) semantics by passing a temp path; passing None is also valid for “skip the global layer entirely”.)

pub fn load_from_cwd() -> Result<Self>

Convenience: load from current working directory.

pub fn apply_env(&mut self)

Apply environment variable overrides in-place.

DEPRECATED: Environment variable overrides are being phased out in favor of file-based configuration (the global settings file). This method is kept for CI/CD compatibility but should not be relied upon for local development. Use oxicode config set or oxicode setup instead.

Supported variables (CI/CD only):

Env var	Setting
OXICODE_MODEL	default_model
OXICODE_PROVIDER	default_provider
OXICODE_THINKING	thinking_level
OXICODE_THEME	theme
OXICODE_MAX_TOKENS	max_tokens
OXICODE_TEMPERATURE	default_temperature
OXICODE_SESSION_DIR	session_dir
OXICODE_EXTENSIONS_ENABLED	extensions_enabled
OXICODE_AUTO_COMPACTION	auto_compaction
OXICODE_TOOL_TIMEOUT	tool_timeout_seconds
OXICODE_DISABLED_TOOLS	disabled_tools

pub fn from_env() -> Self

Build a Settings instance from only environment variables (all other fields stay at defaults).

DEPRECATED: Returns defaults since env overrides are disabled. Use Settings::load() to load from settings.toml instead.

pub fn save(&self) -> Result<()>

Save settings to the global config file.

Preserves the format of the existing canonical file; otherwise saves as JSON. Writes always land in the canonical home — a legacy ~/.oxicode file is never modified (see Self::settings_path for the read-side fallback).

pub fn save_to(&self, path: &Path) -> Result<()>

Save settings to a specific path, using the format determined by the file extension.

pub fn save_project(&self, project_dir: &Path) -> Result<()>

Save settings to the project-local config file.

Uses the format of the existing file if present, otherwise saves as JSON.

pub fn serialize_for_format( settings: &Settings, format: SettingsFormat, ) -> Result<String>

Serialize settings to a string in the specified format.

pub fn parse_from_str(content: &str, format: SettingsFormat) -> Result<Settings>

Parse settings from a string in the specified format.

pub fn merge_cli(&mut self, model: Option<String>, provider: Option<String>)

Merge with CLI arguments (CLI takes precedence).

Arguments

• model — CLI-specified model override
• provider — CLI-specified provider override

pub fn effective_model(&self, cli_model: Option<&str>) -> Option<String>

Get the effective model ID (provider/model format). Returns None if no model is configured.

pub fn effective_provider(&self, cli_provider: Option<&str>) -> Option<String>

Get the effective provider. Returns None if no provider is configured.

pub fn effective_temperature(&self) -> Option<f64>

Get the effective temperature, preferring default_temperature (f64) over temperature (f32), falling back to None.

pub fn effective_max_tokens(&self) -> Option<usize>

Get the effective max tokens, preferring max_response_tokens (usize) over max_tokens (u32), falling back to None.

pub fn save_last_used(model_id: &str)

Save the last used model/provider and persist to disk.

Splits the model_id on first / to store provider and model separately.

pub fn save_theme(&mut self, name: &str) -> Result<()>

Save the current theme to settings and persist to disk.

pub fn get_theme_name(&self) -> String

Get the theme name from settings, returning a default if not set.

Trait Implementations

impl Clone for Settings

fn clone(&self) -> Settings

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Settings

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Settings

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Settings

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Settings

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.