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 agent_hub_enabled: bool,
    pub snapcompact_enabled: bool,
    pub mermaid_render_enabled: bool,
    pub commit_tool_enabled: bool,
    pub memory_enabled: bool,
    pub memory_db_path: Option<PathBuf>,
    pub mnemopi_engine: bool,
    pub memory_backend: Option<String>,
    pub memory_llm_extract: bool,
    pub memory_llm_extract_model: String,
    pub embedding_provider: String,
    pub embedding_base_url: Option<String>,
    pub embedding_api_key_env: String,
    pub embedding_model: String,
    pub ttsr_enabled: bool,
    pub ttsr_interrupt_mode: String,
    pub model_roles: HashMap<String, String>,
    pub advisor: AdvisorSettings,
}

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 Theme::by_name (e.g. “oxi_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: ~/.oxi/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 to the Action enum in oxi-tui.

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.

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.

commit_tool_enabled: bool

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

memory_enabled: bool

Enable session-spanning memory tools (retain/recall/reflect/edit). Default: false (opt-in).

memory_db_path: Option<PathBuf>

Path to the SQLite memory database. Default: ~/.oxi/memory/<project>.db when empty.

mnemopi_engine: bool

Use the Mnemopi engine (FTS5 + vector recall) instead of the basic SQLite LIKE-search backend. Requires memory_enabled = true. Default: false (uses basic SqliteMemoryStore).

memory_backend: Option<String>

Backend selector for the autonomous memory pipeline (omp local-backend analog). None (default) disables the pipeline; Some("local") enables per-session extraction

• cross-session consolidation.

memory_llm_extract: bool

LLM fact extraction for memory_retain. When true, the memory_retain tool is wrapped so each put(content, …) call is sent through the configured model’s structured-extraction prompt and the resulting atomic facts are stored individually.

memory_llm_extract_model: String

Model pattern used for LLM fact extraction when memory_llm_extract = true. Empty means “use the session’s default model”.

embedding_provider: String

Embedding provider for the Mnemopi engine. One of:

• "none" (default) — recall runs in FTS5-only mode.
• "remote" — OpenAI-compatible /v1/embeddings.

embedding_base_url: Option<String>

Base URL for the remote embedding provider (no trailing slash).

embedding_api_key_env: String

Env-var holding the remote-embedding API key (so the key never lands in settings.toml). Default OPENAI_API_KEY.

embedding_model: String

Logical embedding model name. Recorded alongside stored embeddings for cache keying and diagnostics.

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 oxi_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 oxi_agent::advisor engine wired into AgentSession.

Implementations

impl Settings

pub fn settings_dir() -> Result<PathBuf>

Get the global settings directory path (~/.oxi).

pub fn settings_toml_path() -> Result<PathBuf>

Get the global settings TOML file path (~/.oxi/settings.toml).

pub fn settings_json_path() -> Result<PathBuf>

Get the global settings JSON file path (~/.oxi/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, returns the JSON path by default.

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 the preferred path if neither exists.

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 .oxi/settings.json first, then .oxi/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 → ~/.oxi/sessions.

pub fn load() -> Result<Self>

Load settings, applying all layers:

1. Built-in defaults
2. Global ~/.oxi/settings.toml
3. Project .oxi/settings.toml
4. Environment variable overrides

Examples

use oxi_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>/.oxi/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 ~/.oxi/settings.{toml,json}. 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 (~/.oxi/settings.toml). This method is kept for CI/CD compatibility but should not be relied upon for local development. Use oxi config set or oxi setup instead.

Supported variables (CI/CD only):

Env var	Setting
OXI_MODEL	default_model
OXI_PROVIDER	default_provider
OXI_THINKING	thinking_level
OXI_THEME	theme
OXI_MAX_TOKENS	max_tokens
OXI_TEMPERATURE	default_temperature
OXI_SESSION_DIR	session_dir
OXI_EXTENSIONS_ENABLED	extensions_enabled
OXI_AUTO_COMPACTION	auto_compaction
OXI_TOOL_TIMEOUT	tool_timeout_seconds
OXI_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.

Uses the format of the existing file if present, otherwise saves as JSON. Preserves backward compatibility with existing TOML files.

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.