Struct Config 

pub struct Config {

    pub workspace: PathBuf,
    pub api_base: String,
    pub api_key: Option<String>,
    pub model: String,
    pub provider_type: String,
    pub preset: Option<String>,
    pub max_steps: usize,
    pub temperature: f64,
    pub system_prompt: String,
    pub retry_max: usize,
    pub retry_initial_backoff_secs: u64,
    pub retry_max_backoff_secs: u64,
    pub shell_timeout_secs: u64,
    pub headless: bool,
    pub memory_summary_limit: usize,
    pub thinking_budget: Option<u32>,
    pub session_name: Option<String>,
}

Fields

workspace: PathBuf

api_base: String

api_key: Option<String>

model: String

provider_type: String

preset: Option<String>

Preset id resolved from provider.preset in the config file. None when the user did not opt in (or the file was absent).

max_steps: usize

temperature: f64

system_prompt: String

retry_max: usize

retry_initial_backoff_secs: u64

retry_max_backoff_secs: u64

shell_timeout_secs: u64

headless: bool

Run in headless mode: interactive tools go through external hooks instead of waiting for terminal input. If no hook approves the call, the tool is auto-denied.

memory_summary_limit: usize

thinking_budget: Option<u32>

Extended thinking budget for models that support it (e.g. Anthropic claude-3-7). None = model default; Some(0) = disable thinking; Some(n) = budget_tokens.

session_name: Option<String>

Optional display name for the session, shown in the /resume picker.

Implementations

impl Config

pub fn from_env() -> Result<Self>

Load from environment, with config file (~/.recursive/config.toml) as fallback.

Precedence (highest first), applied to api_base / api_key / model / provider_type:

1. env var (e.g. RECURSIVE_API_BASE, OPENAI_API_KEY)
2. explicit field in the file’s [provider] section
3. preset field — provider.preset = "<id>" looks up the bundled providers.toml and takes its api_base / default_model / provider_type. For api_key, step 3 instead consults std::env::var(preset.key_env) (e.g. DEEPSEEK_API_KEY).
4. hardcoded default

The api_key chain is asymmetric: the generic env vars in step 1 (RECURSIVE_API_KEY / OPENAI_API_KEY) rank above the file’s explicit api_key, but a preset’s specific env var in step 3 ranks below it. Inverting step 3 would silently override a user’s api_key = "sk-old" whenever DEEPSEEK_API_KEY happened to be in their shell.

The API key is optional here so commands that don’t need the LLM (e.g. tools, config) still run.

pub fn require_api_key(&self) -> Result<&str>

Return the API key or a descriptive error if none was configured.

pub fn validate_for_agent(&self) -> Result<(), String>

Validate that the config has enough information to run the agent. Returns a user-friendly error message if not.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Config

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

Formats the value using the given formatter.