Skip to content

Lua API

Reference for every namespace exposed under the global smelt table. Rust-registered signatures come from the closure's argument and return types; bundled Lua signatures come from LuaCATS annotations beside the implementation.

Coverage: 93 namespace(s), 450 function(s), 111 class(es), 13 alias(es).

Namespaces marked UI only need the terminal UI and raise in headless mode. Advanced namespaces are low-level building blocks that may change more freely. For a guided introduction, see Extend smelt.

IDE completion

smelt mirrors type stubs for every namespace to builtins/lua/smelt/_meta/ in its data directory. Point lua-language-server at it for completions and diagnostics; see Editor setup.

Core

  • smelt (some UI only): Root smelt namespace. 1 advanced function(s).
  • smelt.builtins: Opt out of bundled smelt.<dotted> modules.
  • smelt.cli: Declare and read CLI flags from Lua.
  • smelt.cmd (some UI only): Register and list slash commands.
  • smelt.config (UI only): Resolved application configuration introspection.
  • smelt.defaults: Startup fallbacks for new sessions.
  • smelt.events: Occurrence-oriented subscriptions for events such as turn_start, tool_start, and turn_complete.
  • smelt.keymap: Register chord→callback bindings and inspect the layered help index.
  • smelt.lifecycle: Host-phase hooks keyed by event name.
  • smelt.reg: Helpers for constructing Reg handles.
  • smelt.remember: Per-key opt-in to last-used recall on launch.
  • smelt.settings: Metatable-backed proxy table for preferences.
  • smelt.signal: Named reactive values.
  • smelt.state: Per-plugin state.
  • smelt.task: Yield-then-resume coroutine bridge: alloc and resume external tasks. Advanced.
  • smelt.tick: Reload-safe periodic work.
  • smelt.timer: One-shot and recurring timer callbacks.
  • smelt.work (UI only): Push background work-state tokens.

Agent and session

  • smelt.agent: Agent-facing prompt customization for Lua plugins.
  • smelt.auth: Authenticated provider helpers.
  • smelt.engine (some UI only): LLM engine control - cancel, ask, inherited ask, submit commands, and request tool approval.
  • smelt.history (UI only): Prompt history entries and search.
  • smelt.lsp: Generic stdio Language Server Protocol client. Advanced.
  • smelt.mcp: Config-time MCP server registration.
  • smelt.messages: Persistent message log with full bodies and tracebacks.
  • smelt.mode (some UI only): Agent-mode selector.
  • smelt.model (some UI only): Model selector.
  • smelt.permissions (some UI only): Inspect, revoke, and extend permission policy state, or synchronize live session and persisted grants.
  • smelt.provider: List built-in model providers and register custom ones.
  • smelt.reasoning (some UI only): Reasoning-effort selector.
  • smelt.session (UI only): Current session metadata, turn list, message snapshots, rewind, and persisted session management. 9 advanced function(s).
  • smelt.session.messages (UI only): Session messages.
  • smelt.session.slug (UI only): Session slug.
  • smelt.session.title (UI only): Session title.
  • smelt.skills: List and load skill content from the SkillLoader populated at startup.
  • smelt.tips (UI only): Discovery tips shown in the prompt bar and banner.
  • smelt.tools: Register, unregister, and resolve plugin tools for the engine.
  • smelt.trust: Query and mutate the per-project content trust store.

User interface

  • smelt.banner: Startup banner extension point.
  • smelt.buf (UI only): Buffer handle constructor. Advanced.
  • smelt.clipboard: Read and write the system clipboard.
  • smelt.confirm (UI only): Confirm dialog primitives - preview dispatch, back-tab cycling, and choice resolution. 1 advanced function(s).
  • smelt.dialog (UI only): Root-docked modal dialog primitives.
  • smelt.headerline: Optional row above the transcript.
  • smelt.input (UI only): Single-line input handle constructor.
  • smelt.layout: Declarative, width-independent content layout primitives for transcript/tool display. Advanced.
  • smelt.notify (some UI only): Status-area toasts.
  • smelt.overlay (UI only): Overlay handle constructor. Advanced.
  • smelt.paint (UI only): Register Lua callbacks against custom paint regions. Advanced.
  • smelt.picker (UI only): Picker facade. 1 advanced function(s).
  • smelt.prompt (some UI only): The main editable input surface: win handle, text get/set, and cursor control.
  • smelt.spinner: Shared spinner glyph and traveling-wave grayscale color for plugin animations.
  • smelt.statusline (UI only): The statusline at the bottom of the screen.
  • smelt.terminal (UI only): Terminal integration helpers.
  • smelt.theme (some UI only): List bundled colorschemes, or apply, read, and override the active one.
  • smelt.ui (UI only): Screen-composition primitives: main layout composer and per-window renderer registration.
  • smelt.ui.layout (UI only): Composable layout-tree primitives for the retained main TUI layout. Advanced.
  • smelt.vim (UI only): Read and write the vim mode of the focused vim-enabled surface.
  • smelt.win (UI only): Window handle constructor. Advanced.

Transcript and documents

  • smelt.diff: Compact unified-patch indexing, metadata and expandable context folds. Advanced.
  • smelt.document: Indexed read-only documents shared by native data providers and Lua-created windows. Advanced.
  • smelt.render (UI only): Paint text / markdown / syntax-highlighted code / split diffs into a Buf. Advanced.
  • smelt.transcript (some UI only): Transcript display policy and rendered transcript inspection.
  • smelt.transcript.defaults: Bundled default transcript entry points for rendering semantic blocks and raw tool output. Advanced.
  • smelt.transcript.groups: Declarative transcript display grouping.

Files and system

  • smelt.files: Workspace file search.
  • smelt.fs: Sync filesystem primitives.
  • smelt.fs.file_state: Cached file-state tracker used by tools to detect external modifications between reads and writes. Advanced.
  • smelt.git: Asynchronous Git snapshots and explicit file-level staging. Advanced.
  • smelt.grep: Ripgrep wrapper for searching files.
  • smelt.http: Asynchronous HTTP get/post.
  • smelt.http.cache: Runtime-owned HTTP response cache.
  • smelt.notebook: Parse and read notebook cells, apply edits, and compute preview data for the edit_notebook tool. Advanced.
  • smelt.os: Environment and system primitives: getenv, setenv, platform, cwd, pid, etc.
  • smelt.path: Pure path arithmetic: normalize, join, relative, expand, display, etc.
  • smelt.process: Run subprocesses and manage contained shell jobs.
  • smelt.search (UI only): Search controls for the active UI session.
  • smelt.shell: Shell command splitting and interactive/background-operator validators.

Utilities

  • smelt.build: Compile-time build identity and version metadata for plugins.
  • smelt.frontend: Query which frontend is active (TUI vs headless).
  • smelt.fuzzy: Fuzzy-match scoring backed by neo_frizbee (SIMD Smith-Waterman).
  • smelt.html: HTML parsing: title extraction, link scraping, to_text, to_markdown, DDG results.
  • smelt.image: Image file detection and base64 data-URL loading.
  • smelt.inspect (UI only): Local session introspection web UI. Advanced.
  • smelt.json: Encode/decode JSON for Lua plugins.
  • smelt.list (UI only): Picker-style virtual list widget.
  • smelt.log: Structured JSONL log entries written to the engine log file.
  • smelt.metrics (UI only): Metrics ledger access and live perf instrumentation.
  • smelt.metrics.perf (UI only): Perf instrumentation toggle, clear, and snapshot. Advanced.
  • smelt.parse: Pure parsers: frontmatter extraction from markdown documents.
  • smelt.perf: Lightweight scope timers that feed smelt.metrics.perf_snapshot. Advanced.
  • smelt.text: Terminal-cell measurement and pure text formatting. Advanced.
  • smelt.time: Wall-clock time parsing and formatting.

Types

  • Classes & aliases - typed opts records and string-literal unions referenced from the namespace pages.