Construction

local completion = require("term.input.completion")
local theme_mod = require("theme")

local comp, err = completion.new({
    path = "shell.completion.shell",
    tss = theme_mod.subscribe("shell", "completion"),
    sources = {
        "shell.completion.source.bin",
        "shell.completion.source.builtins",
        "shell.completion.source.fs",
        "shell.completion.source.calm",
    },
    -- additional config fields are passed through as comp.cfg
})

The optional tss field is a theme-subscribe thunk (a closure returned by theme.subscribe()). When provided, the engine's default get() uses it for metadata-driven styling — providers no longer need to implement their own get() method.

The path module is loaded and its exported methods are injected directly onto the completion object. Each source module path is loaded and instantiated via its new() constructor.

Primary layer methods

These operate on layer 1 (traditional candidates).

Secondary layer methods

These operate on layer 2 (AI / auxiliary candidates).

Source management

Promotion

When no promote is provided by the provider, the input object falls back to simple append: line = line .. candidate.

Required

-- Populate primary candidates for the given input.
-- Call self:provide() and self:set_meta() inside.
-- cursor_pos is passed when the input has eol_only = false.
search = function(self, input, history, cursor_pos)
    local candidates = self:source("fs"):search(input)
    self:provide(candidates)
    self:set_meta(metadata)
    return self:available()
end

Optional

-- Populate secondary (AI) candidates.
-- Call self:secondary_set() inside.
search_secondary = function(self, input, history)
    local results = self:source("calm"):search(input, opts)
    self:secondary_set(results)
    return true
end

-- Custom styling for the current candidate.
-- Return raw text when promoted=true, styled text otherwise.
-- Not needed when config.tss is set — the engine's default get()
-- uses the tss thunk with the candidate's source metadata.
get = function(self, promoted)
    local l = self.__state.layers[1]
    local variant = l.candidates[l.chosen]
    if promoted then return variant end
    return my_tss:apply(l.meta[l.chosen].source, variant).text
end

-- Apply a candidate to the current line.
-- Return {line = new_line, action = "execute" | nil}.
promote = function(self, candidate, metadata, line)
    return { line = line .. candidate }
end

-- Whether the current candidate must skip common-prefix narrowing.
should_promote_full = function(self)
    return false
end

-- Whether ENTER should auto-promote the current candidate.
should_auto_promote = function(self)
    return false
end

Existing providers

Shell (shell.completion.shell) — command, path, env, history completion with learned subcommands and CALM secondary search.

When the input has arguments, a dispatch table routes known commands (z, x, zx, cd, setenv, unsetenv) to dedicated handler functions. All other commands fall through to the generic chain: dedicated builtin handlers (cmds source), learned subcommands (learned source), then filesystem fallback. When a builtin handler or learned source returns empty candidates, the engine falls through to filesystem completion instead of returning nothing.

Learned subcommands are recorded after each successful command execution (exit code 0): the first positional argument (skipping flags) is stored as a sorted set member in the completions keyspace of shell.mneme, keyed by binary name, with scores tracking frequency. Commands that primarily operate on file paths (rm, ls, cp, mv, stat, rsync) are excluded from recording entirely. For other commands, arguments that look like file paths are filtered out — anything containing /, starting with . or ~, having a file extension, or resolving to an existing filesystem entry is skipped.

Implements promote with replace_prompt / exec_on_prom / trim_promotion / reduce_spaces metadata.

Lua (shell.completion.lua) — keyword and symbol completion for Lua mode. No secondary search.

Source utilities

The shell.completion.utils module provides helpers for the common prefix-match-and-sort pattern used by most sources:

local cu = require("shell.completion.utils")

-- Match array items starting with prefix, return suffixes
cu.match_prefix(items, prefix, opts?)
-- Match table keys starting with prefix, return suffixes
cu.match_prefix_keys(tbl, prefix, opts?)

opts is an optional table: suffix (string to append, default "") and sort (sort by string length, default true).

Built-in sources (shell)

Built-in sources (wiki)

Required methods

-- Render completion candidates at the cursor position.
-- Returns the number of characters drawn (for clearing).
draw = function(self, completion, cursor_col, available_width, tss)
    -- completion: the completion object
    -- cursor_col: cursor column within the visible area
    -- available_width: max drawable characters
    -- tss: TSS instance for styling
    return draw_length
end

-- Erase previously drawn completion.
clear = function(self, draw_length, blank_char)
end

Inline ghost renderer

The default renderer draws a single candidate as dimmed text after the cursor. When both primary and secondary candidates are present and the secondary text starts with the primary text, it merges them: the overlapping prefix is styled as "completion" and the remainder as "secondary".

TSS rules used:

Common fields

Shell-specific fields

These are handled by the shell provider's promote() method, not by the generic engine.

Configuration

local input = require("term.input")

local inp = input.new({
    completion = comp,        -- completion object
    history = hist,           -- history object (passed to search)
    renderer = my_renderer,   -- custom renderer (default: inline ghost)
    eol_only = true,          -- complete only at end-of-line (default)
})

Key bindings

Completion lifecycle

1. User types a character at EOL

2. search_completion() calls completion:search(line, history)

3. Provider queries sources, calls provide() + set_meta()

4. draw_completion() delegates to renderer

5. User presses TAB:

   • Single candidate or should_promote_full(): full promotion

   • Multiple candidates: append common prefix, re-search

6. After promotion: refresh_secondary() triggers secondary search

eol_only flag

When eol_only = false, completion triggers at any cursor position. The cursor position is passed to the provider's search() as the cursor_pos parameter. The provider is responsible for determining what to complete based on cursor position. The promote() method handles how the candidate is inserted (append, replace token, etc.).

Note: the default inline ghost renderer draws at the cursor, which may overwrite text after the cursor in mid-line mode. A popup renderer is recommended for mid-line completion.