Skip to content

Execution Models ​

Matchmaker supports multiple execution strategies for running commands, generating input rows, copying text, transforming state, and executing actions.

IMPORTANT

However broad the following section is, for the most part it only exists so that matchmaker can act consistently with respect to Lua support. You can almost always just use simple inline scripts (the shell command strategy), for which you should consult the template docs instead.


Strategy Overview ​

Every command string (except preview layout commands) is classified into one of four execution strategies based on its prefix:

Prefix / ShapeStrategyDescription
command ...Shell CommandRun via the configured shell (start.shell or $SHELL -c). Supports {} template expansions.
@path [args...]Script FileRuns path through the configured shell (start.shell or $SHELL) with args. Relative paths resolve against the preset's directory.
@./path [args...]Direct FileExecutes the file at path itself (the kernel honors its shebang; the file must be executable). Relative paths resolve against the preset's directory.
#!lua ...Inline LuaRuns inline Lua script on the internal Lua runtime with access to global state and env tables.
@file.lua [args...]Lua Script FileRuns file.lua on the internal Lua runtime, passing args as varargs (...). Relative paths resolve against the preset directory.

NOTE

Lua strategies require the mlua cargo feature (enabled by default). When disabled, #!lua falls back to Shell, and @*.lua falls back to Direct File.

NOTE

Relative files resolve against the parent directory of MM_OVERRIDE. This is exactly the path of the first override passed with -o!


Feature & Action Support Matrix ​

Different contexts in Matchmaker use command strategies in specific ways:

Context / ActionShell@file#!lua@file.luaOutput / Result Handling
Execute, ExecuteSilent, ExecuteAsync, ExecuteThen✓✓✓✓Exit code determining success / continuation
ExecuteOrConfirm, ExecuteAndQuit✓✓✓✓Exit code determining prompt vs. quit policy
Become, BecomeSilent✓✓——Replaces Matchmaker process (exec)
BecomeOrConfirm, BecomeOrResume✓✓——Replaces process with exit code recovery policy
Copy, CopyAsync✓✓✓✓Shell/File captures stdout; Lua uses script return value
Transform, TransformConfig✓✓✓✓Shell/File parses stdout; Lua parses script return value
start.command & Reload / ReloadNext / ReloadPrev✓✓✓✓Shell/File reads piped stdout; Lua calls global inject(line)
start.directory (when exec = true)✓✓✓✓Shell/File captures stdout; Lua uses script return value
Dynamic [envs] (when exec = true)✓✓✓✓Shell/File captures stdout; Lua uses script return value
--list & --list=<ARG>✓✓✓✓Runs command directly outside TUI
preview.layout[].command✓———Strictly Shell execution with {} template expansion

Script File Execution (@) ​

Commands prefixed with @ run a file stored next to the preset:

toml
[binds]
"ctrl-o" = "Execute(@open_file.sh {file})"
"ctrl-y" = "Copy(@format_item.py '{name}' '{path}')"
  • Path Resolution: Relative paths resolve against the directory of the first applied preset (MM_OVERRIDE parent). Absolute paths are used as-is.
  • Argument Preservation: Arguments are split by whitespace. Single quotes ('arg with spaces') preserve whitespace within arguments without shell interpolation.
  • Interpreter: The configured shell (start.shell or $SHELL) reads the file as source in its own language; write the file in that shell's dialect, or use @./ (below) to select the interpreter via shebang.

Direct File Execution (@./) ​

A path starting with ./ is executed through execve, so the kernel honors its shebang and the file runs under its declared interpreter:

toml
[start]
command = "@./zellij.sh sessions"
  • Executable bit required: the file must be executable (chmod +x); otherwise execution fails with a permission error.
  • Shebang honored: @./script.sh runs under the interpreter its shebang names -- use this for bash-specific syntax (arrays, export -f) or any interpreter other than the configured shell.
  • .lua files keep Lua-engine precedence: @./x.lua runs on the internal Lua runtime.

Lua Runtime (mlua) ​

Each Lua execution runs on a fresh, isolated Lua 5.4 VM. Concurrent actions (such as ExecuteAsync background tasks or ExecuteSilent threads) never share or block on VM state.

Inline Scripts (#!lua) ​

A payload starting with #!lua followed by whitespace runs the rest of the string as Lua code:

toml
[binds]
"@open" = '''ExecuteOrConfirm(#!lua local p = state.current and state.current[1]
if p then
  os.execute(string.format("%q -- %q", os.getenv("EDITOR") or "vi", p))
end)'''

Script Files (@file.lua) ​

A @ path ending in .lua executes the file within the Lua engine:

toml
[binds]
"@process" = "ExecuteAsync(@process_item.lua --fast)"

Remaining words become varargs (...) passed to the script.

Input Stream Ingestion (inject) ​

For start.command and Reload, Lua scripts do not write to standard output. Instead, rows are pushed into Matchmaker using the global inject(line) function:

toml
[start]
command = '''#!lua
for _, item in ipairs({ "apple", "banana", "cherry" }) do
  inject(item)
end'''

Or via a sibling file:

toml
[start]
command = "@list_items.lua"

The state Table ​

The global state table provides an execution-time snapshot of the picker:

FieldDescription
state.queryCurrent user search query string
state.modeComma-joined active mode tags
state.rawComplete raw line of the current item (nil if nothing selected)
state.currentCurrent item columns array [1]...[n], also keyed by column names
state.selectedArray of selected items (each item is a column array; mirrors {+})
state.position0-based index of current cursor item
state.totalTotal item count
state.matchedMatched item count
state.selected_countSelected item count
state.active1-based index of the focused column
state.argsTrailing CLI arguments passed after -- (1-indexed array)
lua
#!lua
local selected_paths = {}
for _, item in ipairs(state.selected) do
  if item.path then table.insert(selected_paths, item.path) end
end
return table.concat(selected_paths, "\n")

The env Table ​

The global env table exposes environment variables to scripts (MM_*, FZF_*, and anything you define in [envs]):

lua
local override_dir = env.MM_OVERRIDE and env.MM_OVERRIDE:match("(.*/)")

To access the parent process environment variables (such as $EDITOR or $HOME), use standard Lua os.getenv("EDITOR").

Mode-Gated Lua Binds ​

Because Matchmaker appends a lua mode tag when mlua is enabled, you can provide Lua implementations that gracefully fall back when compiled without Lua:

toml
[binds]
"@copy" = "Copy(echo -n {+})"
"lua^^@copy" = '''Copy(#!lua local t = {}
for _, it in ipairs(state.selected) do t[#t + 1] = it[1] end
return table.concat(t, "\n"))'''

Exit Policies & Lifecycle Handling ​

What happens to the picker after a synchronous command exits depends on the action:

ActionSuccess (exit 0)Non-Zero ExitInterrupted / Ctrl+C / Signal
ExecuteReturns to TUIReturns to TUIReturns to TUI
ExecuteOrConfirmReturns to TUIDisplays confirmation promptReturns to TUI (no prompt on signal)
ExecuteAndQuitQuits MatchmakerReturns to TUIReturns to TUI
BecomeReplaces processReplaces processReplaces process
BecomeOrConfirmQuits MatchmakerDisplays confirmation promptResumes Matchmaker (on Ctrl+C or code 100)
BecomeOrResumeQuits MatchmakerResumes MatchmakerQuits with error (on crash/abnormal exit)

NOTE

Custom helper scripts invoked via BecomeOrConfirm can exit with code 100 to instruct Matchmaker to resume the interactive picker without relying on user interrupts.