Configuration Reference¶

Config file: ~/.config/smelt/init.lua (respects $XDG_CONFIG_HOME).

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 the user init.lua runs, 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: clone the repo and the agent already knows the project's conventions and tooling. It is gated by a content trust system: run /trust once to record the SHA-256 hash of .smelt/. Any edit invalidates the hash and requires re-running /trust.

Reload behavior¶

Lua config reloads are transactional. 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.

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 $XDG_STATE_HOME/smelt/) 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 under $XDG_STATE_HOME/smelt/) 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. Run /reload after editing config to apply changes 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.

Use Brave Search instead of the default DuckDuckGo HTML search by selecting the provider and exporting the configured 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=...

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",
      -- explore = 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.

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¶

All runtime data is stored under the XDG base directories:

OAuth-backed providers store their login state under Smelt's runtime data and can be managed with smelt auth.

Environment Variables¶

CLI Flags¶

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