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.

Manual reload also re-fetches the active model's context-window limit in the background, so server-side context-size changes take effect without restarting the session, even when the model and endpoint are unchanged. For an unchanged model target, the current limit stays in use while discovery runs and if discovery fails. A failed refresh is reported by smelt.config.runtime_status().controllers.context_window; another /reload retries it. An explicit model context_window setting still takes precedence over server metadata.

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:

Custom reasoning models¶

For a custom endpoint that does not advertise reasoning capabilities, declare both support and the server's native levels. For example, a Qwen3.8 vLLM server using the qwen3 reasoning parser can be configured as:

smelt.provider.register("box", {
  type = "openai-compatible",
  api_base = "http://localhost:8080/v1",
  models = {
    {
      name = "orcarouter/Qwen3.8-27B-Uncensored-NVFP4",
      supports_reasoning = true,
      supported_reasoning_efforts = { "off", "low", "medium", "xhigh" },
      default_reasoning_effort = "xhigh",
    },
  },
})

/reasoning offers these levels; unsupported selections fall back to the declared default. Explicit model configuration takes precedence over provider metadata. Use the levels supported by your server and parser version, not generic presets: this server accepts xhigh, not high.

For OpenAI-compatible models with supports_reasoning = true, /reasoning off sends reasoning_effort = "none". Omitting the field would leave thinking at the server's default. Unknown or explicitly non-reasoning models receive no reasoning parameter when off. /thinking off only folds the displayed thinking blocks; it does not disable model reasoning.

Chat Completions reasoning replay is automatic: smelt records the received field (reasoning_content, reasoning, or reasoning_text) and replays it only for the same provider type, endpoint, API and model. No extra setting is needed. Endpoints that return no recognized reasoning field receive no reasoning fields. Disabling new thinking does not discard existing tool-continuation reasoning. Earlier-turn filtering is left to the server's chat template; smelt does not assume which template is deployed. Reasoning without recorded origin, including older sessions, is kept in history but is not replayed in native reasoning fields.

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 picker-visible model in configuration or managed-provider priority order

If the catalog has no picker-visible entries, its first internal model is used as the fallback. 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. Models that providers mark hidden stay out of picker and list surfaces but remain available by explicit provider/model key. 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. The built-in labels are off, low, medium, high, xhigh, max, and ultra, but non-empty provider-defined labels are also accepted and preserved exactly on label-based provider APIs. Budget-based APIs cannot interpret custom labels, so they use the configured max thinking budget. Models explicitly marked as not supporting reasoning only accept off.

/reasoning opens a compact picker with the active model's native levels, marking the current choice and the model default. Command hints and Ctrl+T use the same model capabilities, not a universal effort scale. Provider-advertised levels are authoritative, including labels unknown to this smelt version. Known Claude models have model-specific built-ins. Budget-based presets remain available even when their configured token budgets are identical.

Without advertised levels or a model-specific built-in, smelt reports that the levels are unknown instead of guessing. /reasoning <effort> remains available as an explicit override for these endpoints. A configured --reasoning-cycle can supply a custom cycle for unknown models; for known models it is filtered to supported levels. If none remain, cycling uses the model's supported list. An explicitly empty cycle disables the shortcut.

When switching models, smelt keeps the current effort if supported; otherwise it uses the new model's valid default, then its first supported level, and reports the adjustment. Selecting an unsupported level explicitly returns an error without changing the current effort.

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
smelt.settings.math_rendering = "unicode" -- optional: "graphics" is the default

Display math in Markdown uses \[...\] or $$...$$; inline math uses \(...\) or $...$. The graphics setting renders equations with Kitty graphics using RaTeX and embedded math fonts when the terminal acknowledges a Kitty graphics protocol probe and reports usable pixel dimensions for its cells. Both graphics and Unicode text use the RaTeX parser; Unicode approximates the layout on a terminal character grid. Display equations use a slightly smaller font than terminal text. Those that just exceed the available width are rerendered at up to 20% smaller font size; wider equations use Unicode rather than becoming too small to read. Simple inline expressions in paragraphs, headings, lists and Markdown table cells fit into one text row when they fit the assigned cell width. Inline formulas are not downscaled; taller or too-wide inline formulas use a one-line text fallback instead of shrinking until unreadable or expanding line heights. Fractions stay grouped as (numerator)/(denominator); expressions that cannot be flattened faithfully retain their LaTeX source. In Unicode mode, a formula containing an unsupported RaTeX construct (for example, an indexed root) retains its entire LaTeX source rather than silently omitting part of the expression. If either terminal check fails, an equation cannot be rasterized, or the live image budget fills, smelt uses text instead. Cached and visible images keep their rasters alive for scroll-back; released images free capacity for later equations. The live-image budget is 256 images or 32 MiB of encoded PNGs, plus an 8 MiB recent raster cache. Inside tmux, enable graphics passthrough with set -g allow-passthrough on in tmux.conf and use a terminal that supports Kitty graphics and answers the cell-size query (CSI 16t). tmux without passthrough or without a cell-size reply uses Unicode. Selecting any part of a display equation copies its original Markdown source, including delimiters. Use smelt.settings.math_rendering = "unicode" to always use text rendering.

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=...

Auto-continue and quota pauses¶

smelt.settings.auto_continue controls automatic continuation in interactive sessions: "off" disables it, "goal" continues active goals with auto-continue enabled, and "always" also allows continuation without a goal.

A quota or rate-limit error pauses the interrupted conversation. Queued messages stay visible above the prompt and are not sent while paused. When the provider supplies a reset time and auto-continue allows it, the same row shows quota exceeded · resuming at 14:30 in local time, showing the next attempt. To detect early quota resets, retries back off from 1 minute to 2 minutes, 4 minutes, and then every 5 minutes. The original provider reset time is retained: if it arrives before the next periodic retry, smelt tries just after that reset instead. Later estimates cannot postpone an untried reset deadline, and a retry response that omits reset metadata does not stop an established recovery schedule. Resumption defers while a draft, dialog, or busy task needs attention. If the initial error has no known reset time, the status reads quota exceeded · paused and recovery requires a manual retry.

Press Enter with an empty prompt to retry the interrupted conversation manually. Esc Esc, the usual cancel chord, stops a scheduled retry and cancels foreground busy work without discarding queued messages (close any open picker first). New input submitted during the pause is queued. Resuming retries the original work first; turn-queued messages follow after it finishes. Request-queued steering retains its separate delivery stage. Command-scoped model, sampling, reasoning, and permission overrides survive retries and reloads without being applied to subsequent queued turns. Changes to global settings while paused still apply where the interrupted command has no override.

Background-process completions are recorded during the pause but cannot bypass the retry schedule. A repeated, expired reset time does not trigger rapid retries; periodic backoff continues. Reloading preserves the backoff and the next attempt. Settings and goal changes are rechecked before resuming, and cancellation or a session change invalidates the pending continuation. Successful recovery or a manual resume starts a fresh backoff for any subsequent quota pause.

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.

show_timestamps defaults to true. Set smelt.settings.transcript.show_timestamps = false to hide timestamps on user messages, tool calls, and tool groups without hiding tool execution durations. This preference and its rendering policy are Lua-owned; it is not a --set key. Changes apply to existing transcript blocks as well as new ones.

Timestamps use local time: HH:MM:SS today, mon DD HH:MM:SS on earlier days, and YYYY mon DD HH:MM:SS in earlier years. Undated history stays undated. User timestamps occupy the panel's top padding row, use the theme's SmeltUserTimestamp foreground, and are excluded from copied message text.

smelt.settings.transcript = {
  show_timestamps = true,
  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.