Configuration Reference¶

Config file: ~/.config/smelt/init.lua on Linux and macOS, or %APPDATA%\smelt\init.lua on Windows. $XDG_CONFIG_HOME overrides the config root on every platform.

Load a different file with --config <path>.

If no config file exists, an interactive setup wizard runs on first launch and writes a starter init.lua.

init.lua¶

init.lua is evaluated at startup before the engine starts. It can register providers, MCP servers, settings, and permission rules by calling APIs on the smelt table. Anything else you put in the file (custom commands, keymaps, autocmds) behaves like a plugin and is also loaded at startup.

Per-project config¶

After bundled autoload modules, the user init.lua, and global user plugins run, smelt looks for .smelt/init.lua and .smelt/plugins/*.lua under the current working directory and sources them. Project-local config is especially useful on teams: after reviewing and trusting it, a fresh clone carries the project's conventions and tooling. Run /trust to record the current SHA-256 hash of .smelt/; any edit invalidates that hash and requires review and trust again.

Reload behavior¶

smelt-managed configuration and registrations reload transactionally. smelt loads and validates a fresh candidate before replacing the running generation. If any early, autoload, user, project, or plugin file raises or contains invalid syntax, the current commands, keymaps, tools, hooks, providers, settings, permissions, MCP/LSP declarations, and watcher roots remain active. Candidate on_ready hooks do not run.

This guarantee covers declarations and resources owned by smelt's generation machinery. Lua configuration is trusted in-process code, not a sandbox: arbitrary filesystem, process, network, or other external effects are not rolled back when a candidate fails. APIs that directly affect the live application are unavailable during candidate evaluation.

A successful /reload reconciles providers, models, settings, permissions, modes, MCP, LSP, and watched config roots as one committed generation. Background controller work is revisioned, so an older connection or metadata result cannot replace newer config. Manual /reload also refreshes prompt inputs such as AGENTS.md, skills, and --system-prompt; automatic Lua config reloads do not.

Settings and background model metadata affect requests created after the commit. An active turn keeps its original target and static permission policy. Explicit model, mode, or reasoning changes made by the user take effect at the next provider-request boundary.

For diagnostics, smelt.config.runtime_status() returns sanitized generation and runtime revisions, pending/failure reload state, model availability, managed provider freshness, and desired/observed revisions for background controllers. It never includes credential values or Lua source contents.

Providers¶

Register a provider with smelt.provider.register:

smelt.provider.register("ollama", {
  type = "openai-compatible",
  api_base = "http://localhost:11434/v1",
  models = { "qwen3.6:27b" },
})

smelt.provider.register("openai", {
  type = "openai",
  api_base = "https://api.openai.com/v1",
  api_key_env = "OPENAI_API_KEY",
  models = { "gpt-5.5" },
})

Re-registering the same name replaces the previous entry. Unknown type values fall back to openai-compatible.

Provider Types¶

Model Configuration¶

Models can be plain strings or tables with per-model overrides:

smelt.provider.register("ollama", {
  type = "openai-compatible",
  api_base = "http://localhost:11434/v1",
  models = {
    { name = "qwen3.6:27b", temperature = 0.8, top_p = 0.95, top_k = 40, min_p = 0.01, repeat_penalty = 1.0 },
    { name = "custom-model", input_cost = 2.0, output_cost = 8.0, cache_read_cost = 0.5, cache_write_cost = 0.0 },
  },
})

Per-model overrides:

Pricing¶

Cost tracking is built in for popular models (GPT, Claude, DeepSeek). Subscription-backed providers such as Codex, Copilot, and Kimi Code are shown as zero-cost because they are included with your subscription. The session cost is shown in the status bar and the running total appears in /stats.

For models not in the built-in table, or to override built-in prices, set cost fields on the model config. All values are USD per 1 million tokens. Unknown models default to zero cost.

Model Selection¶

Model resolution follows this precedence on a fresh launch:

1. --model CLI flag
2. Last explicitly chosen model (recalled from recent.json)
3. smelt.defaults.set{ model = "..." } in init.lua
4. First model in the providers list

Switch models at runtime with /model. The choice is recorded in recent.json in the state directory and restored on the next launch. To always start from smelt.defaults and ignore the last pick, set smelt.remember.set({ model = false }) in init.lua.

OAuth-backed Codex, Copilot, and Kimi Code catalogs load from cache for the first frame and refresh in the background. Fresh models and capability metadata become available in the running picker without a restart. Login, logout, account changes, and authoritative empty catalogs are reflected live without discarding the saved selection key.

The TUI can run while a requested model is pending or unavailable. In that state smelt.model.current() returns nil, and model-backed actions fail with a clear message instead of dispatching an empty model name. smelt.model.status() reports the requested key, availability reason, and sanitized managed-provider refresh status.

Modes and Reasoning¶

Starting mode and reasoning effort can be set via CLI flags or in init.lua. Both are toggleable at runtime: Shift+Tab cycles modes, Ctrl+T cycles reasoning.

Reasoning effort controls how deeply the model thinks before responding. Supported by Anthropic (thinking), OpenAI (reasoning), and any openai-compatible / anthropic-compatible provider that supports reasoning_effort. For OpenAI, max maps to xhigh. Models that don't support thinking ignore this setting.

openai-compatible providers default the reasoning cycle to off,low,medium,high; everything else adds max. The currently active effort is always included in the cycle.

Set thinking block presentation at runtime with /thinking [open|close|peek|toggle].

Defaults vs. last-used¶

Smelt distinguishes two layers for model / mode / reasoning effort:

• Defaults in init.lua are the cold-start values, used when there is no recorded last-used pick.
• Recent (recent.json in the state directory) is what you picked last session. Each launch restores it, so you don't have to re-pick.

Precedence on a fresh launch is CLI flag → recent → defaults → hardcoded fallback. Resuming a session (--resume) takes the session's own saved model / mode / effort, ignoring recent.json.

Pin a cold-start value with smelt.defaults.set{...}:

smelt.defaults.set({
  model = "openai/gpt-5.5",
  mode = "plan",
  reasoning_effort = "high",
})

To make a key always start from smelt.defaults and ignore the last pick, opt out per-key with smelt.remember.set{...}:

smelt.remember.set({
  mode = false,             -- always start in the default mode
  reasoning_effort = false, -- always start at the default effort
  -- model = true (default), still recalls the last model
})

Settings and theme changes¶

smelt.settings.*, smelt.theme.use(...), and smelt.theme.apply(...) apply to the running session and never write to disk themselves. Put settings in init.lua, and defer theme calls with smelt.lifecycle.on_ready(...), to apply them on every launch. Saved Lua config reloads automatically by default; run /reload to apply changes manually without restarting.

Per-plugin Model Preferences¶

Background features (title generation, compaction, prediction, /btw, web_fetch extraction) live in bundled Lua plugins. Each plugin reads its preferred model from smelt.model.preferred("<name>"), falling back to the primary model when unset. Override one from init.lua:

smelt.model.preferred("title", "openai/gpt-5-mini")
smelt.model.preferred("compact", "anthropic/claude-haiku-4-5")
smelt.model.preferred("predict", "openai/gpt-5-mini")

Names used by the bundled plugins: title, compact, predict, btw, web_fetch. Custom plugins can pick any name. References use the same provider/model or bare-model resolution as the primary model.

Settings¶

Set preferences in init.lua by writing to smelt.settings:

smelt.settings.vim = true
smelt.settings.auto_compact = true
smelt.settings.auto_continue = "goal"
smelt.settings.compact_threshold = 0.65
smelt.settings.compact_keep_recent_groups = 1
smelt.settings.show_tps = true

Set settings from init.lua, the --set CLI flag, or any Lua context. Unknown keys raise at the access site; type mismatches raise on assignment.

Read or write via smelt.settings.<key> from init.lua. Saved Lua config reloads automatically by default; run /reload to apply changes manually. Override from the CLI with --set KEY=VALUE. Assigning an unknown key or wrong type raises at the call site.

The default auto search provider uses Brave when its configured API key is available. To require Brave instead of allowing the keyless DuckDuckGo fallback, select it explicitly and export the API key environment variable:

smelt.settings.web_search_provider = "brave"
smelt.settings.brave_search_api_key_env = "BRAVE_SEARCH_API_KEY"

export BRAVE_SEARCH_API_KEY=...

Request audit¶

smelt.settings.request_audit controls the provider-request records stored in each session database:

Full payloads can contain prompts, source excerpts, tool results, and model responses. Treat a session database or smelt export requests output created in this mode as sensitive. Set SMELT_REQUEST_AUDIT=off|summary|full to pin the mode for a process; this environment override takes precedence over Lua config and continues to win after /reload.

Fast mode¶

smelt.settings.fast_mode = true requests accelerated inference at startup. The active model must resolve supports_fast_mode = true from explicit model config or provider metadata. /fast on|off|toggle changes the current session; unsupported models reject the command. Provider-specific billing or quota rules still apply.

Notifications¶

Terminal notification preferences are a nested table, not scalar --set keys:

smelt.settings.notifications = {
  turn_end = true,
}

turn_end defaults to false. The /notify command can enable the next notification or override the setting for the current session without editing config.

smelt.settings.transcript is an additional Lua table for transcript display preferences. It is not a scalar --set key. Use view to set default fold states: "collapsed", "peek", or "expanded" for block kinds, tool names, and group names; use false to disable a built-in group. Use limits for UI-only row caps.

smelt.settings.transcript = {
  view = {
    blocks = { thinking = "peek" },
    tools = {
      load_skill = "collapsed",
      read_file = "collapsed",
      grep = "collapsed",
      glob = "collapsed",
      web_fetch = "collapsed",
      write_file = "expanded",
      edit_file = "collapsed",
      edit_notebook = "expanded",
    },
    groups = {
      explore = "collapsed",
      lsp = "collapsed",
      web = "collapsed",
      -- explore = false,
      -- lsp = false,
      -- web = false,
    },
  },
  limits = {
    tool_rows = 20,
    tool_header_rows = 20,
    tool_body_rows = 20,
    tool_output_rows = 20,
    collapsed_error_rows = 4,
    thinking_peek_rows = 4,
    thinking_peek_head_rows = 1,
  },
}

Override any setting from the CLI with --set KEY=VALUE. Boolean values must be true/false; numeric values are parsed as floats; string values are passed through as-is and validated against the schema's allowed-choice list (if any).

Theme¶

The task slug color is session-specific; change it with /color.

A full colorscheme is a ThemeSpec: a Lua table with optional name, syntax, and light metadata plus a required groups table. groups is keyed by highlight-group name (SmeltAccent, Comment, SmeltDiffAddBg, …) whose values are either a StyleDecl table ({ fg = ..., bold = true }) or a string referencing another group in the same spec. Built-in colorschemes live at runtime/lua/smelt/colorschemes/<name>.lua; custom ones drop in at ~/.config/smelt/lua/smelt/colorschemes/<name>.lua and load via smelt.theme.use("<name>"). See the customization guide for the full shape; runtime/lua/smelt/colorschemes/default.lua is the worked example. The canonical group names, style roles, ownership, and descriptions are listed in runtime/lua/smelt/colorschemes/_groups.lua.

MCP (Model Context Protocol)¶

Connect external tool servers that expose tools via MCP. Each server runs as a child process communicating over stdio. MCP lets you extend smelt without writing Lua: if a server exists for Postgres, Slack, or your internal API, the agent can use it immediately.

smelt.mcp.register("filesystem", {
  description = "Read and write files under /tmp via MCP.",
  command = { "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp" },
  env = { DEBUG = "true" },
  timeout = 30000,
  enabled = true,
})

MCP tools appear in the agent's tool list with names prefixed by the server name (e.g. filesystem_read_file). They default to "ask" permission.

MCP Permissions¶

MCP tools use a separate mcp ruleset in the permissions config. Patterns are matched against the qualified tool name (servername_toolname). See the Permissions Reference for details.

Skills¶

Skills are on-demand knowledge packs the agent can load via the load_skill tool. They keep the system prompt lean: only the skills relevant to the current task are injected, so the agent stays focused and you save context tokens.

They are scanned from these directories (later entries override):

1. ~/.config/smelt/skills/*/SKILL.md, global user skills
2. ~/.claude/skills/*/SKILL.md, global Claude-compatible skills
3. ~/.agents/skills/*/SKILL.md, global Agent Skills-compatible skills
4. .smelt/skills/*/SKILL.md, project-local smelt skills
5. .claude/skills/*/SKILL.md, project-local Claude-compatible skills
6. .agents/skills/*/SKILL.md, project-local Agent Skills-compatible skills

Skill Format¶

Each skill is a directory containing a SKILL.md file:

skills/
  frontend-design/
    SKILL.md
    reference/
      examples.html

SKILL.md uses YAML frontmatter:

---
name: frontend-design
description: Create production-grade frontend interfaces
---

## Instructions

Detailed instructions for the agent...

Permissions¶

See Permissions Reference for full details.

Storage Paths¶

smelt uses four platform directories: config, state, data, and cache. Paths elsewhere in the documentation use these names rather than assuming an operating system.

On Linux and macOS, they are stored under the XDG base directories:

Windows uses %APPDATA%\smelt for config and %LOCALAPPDATA%\smelt\state, %LOCALAPPDATA%\smelt\cache, and %LOCALAPPDATA%\smelt\data for the other roots. Explicit XDG variables override these defaults on every platform.

OAuth-backed providers load credentials in this order: a provider-specific environment override, a private JSON file in the state directory, then the operating system's native keyring. Background status and model-cache checks stop before the keyring, so they never open an operating-system credential prompt. A provider operation can recover a keyring-only credential and copy it to the private file after one successful read. smelt auth writes both file and keyring storage. The files are codex_auth.json, copilot_auth.json, and kimi_code_auth.json, with mode 0600 on Unix. Logout removes both copies.

Environment Variables¶

The OAuth override variables contain each provider's complete JSON credential record, not a single API key. They have highest load priority and are intended for controlled automation; avoid shell history and process environments that other users can inspect.

CLI Flags¶

CLI flags override config values for the current run. See the CLI Reference for the full list.