Lua API
Maki plugins are plain Lua files. Everything a plugin can touch lives under
one global table: maki. This reference documents every module, function,
and method. It is generated straight from the source code by maki-docgen.
For where plugin files live and how to load them, read the
Plugins guide first.
The API tries to mirror Neovim as much as possible (maki.fs, maki.uv,
maki.treesitter, maki.keymap, maki.base64), signatures are kept identical
so code can be copy-pasted between the two without too many modifications.
Plugins run compiled to native code (Luau JIT). If you are debugging a
plugin and want full backtraces, start maki with --no-jit: it runs your
Lua on the interpreter with complete debug info instead.
A small plugin looks like this:
maki.api.register_command({
name = "greet",
description = "Say hello from Lua",
handler = function()
maki.ui.flash("hello from a plugin!")
end,
})
How to read this reference
Signatures use Neovim notation: {path} is a required argument, {opts?}
is optional, and {...} is variadic.
One convention to remember: fallible runtime operations return a
(value, err) pair instead of throwing. Check err before using value:
local text, err = maki.fs.read("config.json")
if err then
maki.log.error("read failed: " .. err)
return
end
Lua errors are reserved for programmer mistakes, like passing a number where a string belongs.
Permissions and plugin.toml
Sensitive APIs are gated per plugin file, and every gated function's entry in
this reference names the permission it needs. A gated call without its
permission raises permission denied: '<name>' not granted for this plugin.
Inside an action of your plugin, a call also raises when the capability
of the action leaves its permission out, see
maki.api.register_action.
fs_read: reading files, and locating the directories maki keeps them infs_write: creating, changing, and removing filesnet: outbound network requestsrun: starting processesenv: reading the process environment, where secrets liveagent: starting model turns: prompting a chat, or running its own sessionssession_read: reading conversation content: session history, the chat input draft, and the content fields of eventssession_write: adding to, removing, or creating conversation content: new sessions, prompts, notices, and deleting sessions or task transcriptssession_settings: changing how a session runs without touching its content: mode, title, model, thinking, fast mode, working directory, and workflowinput: changing the chat input, which is what your next Enter sends
Grants come from a plugin.toml next to the Lua file (for
~/.config/maki/init.lua that is ~/.config/maki/plugin.toml):
min_maki_version = "0.4.12"
[permissions]
fs_read = true
fs_write = true
net = true
run = true
env = true
agent = true
session_read = true
session_write = true
session_settings = true
input = true
The rules:
- No
plugin.tomlat all: every permission is denied, and maki logs a warning at load time. plugin.tomlexists: permissions default to granted. Set a key tofalseto revoke it. An empty file grants everything.- Invalid TOML: everything denied, with a warning in the log.
- A package, or a plugin maki ships, is read the other way round: a key it
does not name is not requested, so its
plugin.tomllists everything it uses. Only aplugin.tomlyou wrote yourself defaults to granted. net_hostsnarrowsnet = trueto a host allowlist, such as["api.acme.com", "*.acme.dev"]. Without it,netreaches any public host. A plugin that registers a provider must set it. See Plugin egress.min_maki_versionis optional and takes a plain semantic version as a lower bound, so ranges do not work. When the field is invalid or the running version is older, Maki skips the Lua in that directory and warns at startup instead of failing. The same floor applies to an installed package, which is skipped while the rest keep loading.--no-pluginsstill skips every user plugin at once.
Overview
| Module | What it is for |
|---|---|
maki | The global entry point. |
maki.pack | Declare global packages and inspect package state. |
maki.api | Plugin registration. |
maki.plan | Plan-mode surface for plugins. |
maki.agent | Subagent primitives for plugins that need to talk to an LLM. |
maki.agent.Session | A subagent session with its own conversation history. |
maki.async | Tools for running things concurrently in Lua plugins. |
maki.async.Semaphore | A counting semaphore for limiting how many tasks run at once. |
maki.async.Permit | One slot in a semaphore, obtained from Semaphore:acquire(). |
maki.async.Task | Handle returned by maki.async.spawn. |
maki.base64 | Base64 encoding and decoding, modelled after vim.base64. |
maki.env | Paths to maki's own directories (config, state, logs, legacy). |
maki.fn | Process and environment helpers, modeled after Neovim's vim.fn job control. |
maki.fs | File-system utilities, modelled after vim.fs and vim.uv. |
maki.image | Small building blocks for working with images: probe metadata, decode pixels, resize, and encode back to bytes. |
maki.image.Image | An image you can inspect, resize, and re-encode. |
maki.interpreter | Run Python code in a memory-safe, time-limited sandbox. |
maki.json | JSON encoding, decoding, and schema validation. |
maki.json.SchemaValidator | A compiled JSON Schema validator. |
maki.keymap | Key mappings, modeled after vim.keymap. |
maki.log | Structured logging for plugins. |
maki.model | The model behind the focused session. |
maki.net | HTTP, plain TCP, and Unix sockets for plugins. |
maki.net.Conn | A TCP or Unix socket connection, from maki.net.connect, maki.net.connect_unix or Listener:accept. |
maki.net.Listener | A Unix socket listener opened by maki.net.listen_unix. |
maki.provider | Providers implemented in Lua. |
maki.provider.auth | Credential storage for the providers this plugin registered. |
maki.session | Host session primitives. |
maki.Timer | Handle returned by maki.defer_fn. |
maki.task | The subagents of the focused session and their transcripts. |
maki.text | Text utilities: format conversion, UTF-8 decoding and the fuzzy matcher the built-in pickers use. |
maki.treesitter | Tree-sitter parsing and query API. |
maki.treesitter.language | Language registry for tree-sitter grammars. |
maki.treesitter.query | Query compilation and lookup. |
maki.treesitter.Query | A compiled tree-sitter query. |
maki.treesitter.Tree | A parsed syntax tree. |
maki.treesitter.Node | A single node in a parsed syntax tree. |
maki.treesitter.LanguageTree | Manages parsing of a source string for a single language. |
maki.ui | Functions for building interactive UI. |
maki.ui.Win | Handle to a floating or split window. |
maki.ui.Buf | A content buffer that holds styled lines of text. |
maki.uv | System and environment utilities, modelled after vim.uv. |
maki.version | Version parsing and comparison with the same API as Neovim's vim.version. |
maki.yaml | YAML encoding and decoding. |
maki
The global entry point. Every API lives under this table.
maki.setup()
maki.setup({config})
Apply your personal configuration. This is only available inside init.lua (not in plugins) and can be called at most once. The table accepts the same keys as the Configuration reference.
Parameters:
{config}(table) Configuration table.
Example:
maki.setup({
model = "opus",
keymaps = false,
})
maki.split()
maki.split({s}, {sep}, {opts?})
Split {s} at each occurrence of {sep} and return the pieces as a
list. Mirrors Neovim's vim.split, so code using it can be copied
between Neovim and maki. {sep} is a Lua pattern unless plain is
set; an empty {sep} splits into single characters.
Parameters:
{s}(string) String to split.{sep}(string) Separator: a Lua pattern, or literal text withplain.{opts?}(table?) Optional settings:plain(boolean?) treat {sep} as literal text instead of a pattern.trimempty(boolean?) drop empty pieces from the start and end of the result.
Returns: (table) List of split pieces.
Example:
maki.split("a,b,c", ",") -- { "a", "b", "c" }
maki.split("x*y*z", "*", { plain = true }) -- { "x", "y", "z" }
maki.split("\nhello\nworld\n", "\n", { trimempty = true }) -- { "hello", "world" }
maki.packadd()
maki.packadd({name})
Load an installed package that is not active.
Parameters:
{name}(string) Package name.
maki.defer_fn()
maki.defer_fn({callback}, {ms})
Run {callback} once after {ms} milliseconds. It fires even if the tool
call that scheduled it has ended or was cancelled, which is what a
self-dismissing toast needs. For repeating work, use a
maki.async.sleep loop inside maki.async.spawn.
You get back a handle. Its :stop() cancels a callback that has not
fired yet, which is how you debounce: schedule, then stop and
reschedule on every new event. An error raised by the callback is
logged and dropped, since nobody is waiting for a result.
Parameters:
{callback}(function) Called with no arguments.{ms}(integer) Delay in milliseconds. Zero fires on the next tick.
Returns: (maki.Timer) Handle with :stop() to cancel before it fires.
Example:
-- A toast that dismisses itself 4 seconds later:
local buf = maki.ui.buf({ scratch = true })
buf:line("copied!")
local win = maki.ui.open_win(buf, { split = "right", width = 20, height = 3 })
maki.defer_fn(function() win:close() end, 4000)
-- Repaint only after the user has stopped typing for half a second:
local pending
local function repaint_soon()
if pending then
pending:stop()
end
pending = maki.defer_fn(repaint, 500)
end
maki.notify()
maki.notify({msg}, {level?}, {opts?})
Show a one line notice. By default it goes to maki.ui.flash, with
{opts.title} in front of the message when you pass one. Without a UI
(maki -p, the sdk, ACP), the notice goes to the log.
There is one handler for the whole process. Once a plugin calls
maki.set_notify_handler, notices from every plugin go through it.
That is how a UI plugin turns flashes into stacked toasts without
any of the callers knowing about it.
{level} reaches the handler untouched, and the default ignores it.
Parameters:
{msg}(string) Notice text.{level?}(string?) Optional. Severity name such as "info", "warn" or "error".{opts?}(table?) Optional.title(string) labels the notice. Free form otherwise.
Example:
maki.notify("saved!")
maki.notify("build failed", "error", { title = "make" })
maki.set_notify_handler()
maki.set_notify_handler({handler})
Install the handler that every maki.notify call in the process goes
through, in place of the default flash. Pass nil to put the default
back.
The handler runs on the Lua thread, so keep it short and hand real
work to maki.async.run. If it raises an error, the error is logged
and the notice falls back to maki.ui.flash, so the user still sees
it. Unloading the plugin that installed the handler also restores the
default.
Parameters:
{handler}(function|nil) Handlerfunction(msg, level?, opts?), or nil.
Example:
local Toast = require("maki.toast")
maki.set_notify_handler(function(msg, level, opts)
Toast.show(msg, { title = opts and opts.title, level = level })
end)
maki.deepcopy()
maki.deepcopy({orig}, {noref?})
Copy {orig} and every table inside it, keeping each table's metatable.
That is what lets a copied empty array still encode as [] instead of
{}. Use it instead of a hand-rolled copy for anything you pass back to
maki. Table keys are copied too. Functions, userdata (including
maki.NIL) and other non-table values are shared, not copied.
A table reachable twice is copied once, so shared references and cycles survive. Pass {noref} to copy such a table every time it is reached. That is faster for trees, but a cycle then fails with an error.
Parameters:
{orig}(any) Value to copy.{noref?}(boolean?) Optional. When true, shared references are not tracked.
Returns: (any) The copy.
Example:
local input = maki.json.decode('{"files": []}')
local copy = maki.deepcopy(input)
copy.mode = "strict"
print(maki.json.encode(copy)) -- {"files":[],"mode":"strict"}
maki.NIL
maki.NIL
maki.NIL is a value that stands for JSON null, like vim.NIL. maki.json.decode returns it for every null unless luanil says otherwise. Every conversion to JSON turns it back into null. So a decode, change, encode pass loses no key. It is truthy and not equal to nil, so test x == maki.NIL for null. Tool handler arguments and event payloads use nil for null instead, never maki.NIL.
Example:
local t = maki.json.decode('{"a": null}')
assert(t.a == maki.NIL)
print(maki.json.encode(t)) -- {"a":null}
maki.pack
Declare global packages and inspect package state.
add is available only in the global init.lua. get is read-only
and is available in project config and packages.
maki.pack.add()
maki.pack.add({specs}, {opts?})
Declare global packages after the global init.lua finishes.
Parameters:
{specs}(table) Sources or tables withsrc,name,version, anddata.{opts?}(table?)confirmcontrols source confirmation.loadis a boolean or a custom loader function.
Example:
maki.pack.add({
{ src = "https://github.com/user/maki-goal", version = "main" },
})
maki.pack.get()
maki.pack.get({names?}, {opts?})
Get package state without changing the installed set.
Reading the lockfile yields, so this cannot run in a callback that must
not yield, like a table.sort comparator or a metamethod.
Parameters:
{names?}(table?) Package names. Omit for all managed packages.{opts?}(table?) Reserved. Omit it.
Returns: (table?, string?) Package records with spec, path, rev, and
active, or nil plus an error when the pack lockfile cannot be read.
maki.api
Plugin registration. This is where you tell maki about your tools, slash commands, and prompt contributions.
Most plugins only need register_tool and maybe register_prompt_hint.
Call these at the top level of your plugin file (during load).
maki.api.register_tool({ name = "greet", ... })
maki.api.register_prompt_hint({ slot = "tool_usage", content = "..." })
maki.api.register_tool()
maki.api.register_tool({spec})
Register a new tool the agent can call. This is the main way plugins add capabilities to the agent. The tool is queued during plugin load and committed to the registry once the plugin finishes loading.
Your {spec} table must include a name, a description (the model reads it
to decide when to use the tool), a JSON Schema for the input, and a handler
function. The handler receives (input, ctx) and returns either a plain
string or a table with richer output fields.
Invalid UTF-8 in the returned text becomes U+FFFD.
ctx:output_mode() returns "compact" when the result goes to the model and
"full" when code such as code_execution made the call. Apply output limits
only in compact mode.
Parameters:
{spec}(table) Tool specification:name(string) Required. ASCII identifier, up to 64 chars ([a-zA-Z_][a-zA-Z0-9_]*).description(string) Required. Non-empty description shown to the model.schema(table) Required. JSON Schema object describing the tool's input parameters.handler(function) Required. Called with(input, ctx)when the tool is invoked. Must return a string or a table with any of these fields:llm_output(string) Result text for the model or the calling code.is_error(boolean) When true, the result is treated as an error.body(BufHandle) Rich rendered body shown in the UI.header(BufHandle) One-line header shown before the body.format(string) "plain" (default) or "markdown".annotation(string) Short label shown next to the tool call.written_path(string) Path of a file written by the tool.diff_path(string) Path for a diff output block.diff_before(string) Before text of the diff.diff_after(string) After text of the diff.image(maki.image.Image|table) An Image, or { media_type: string, data: string } base64 image.state(any) Serializable state forwarded to restore.
audiences(string[]) Which model audiences see the tool. Values: "main", "sub", "all". Default: all audiences.kind(string) Optional grouping label (e.g. "filesystem").timeout(number) Execution timeout in seconds. 0 or false disables. Default: inherits agent deadline.header(function) Optional. Called before execution, returns a string or BufHandle for the one-line header.restore(function) Optional. Called to re-render a previous tool result. Receives(tool_name, input, output, ctx).start(function) Optional. Called when the tool call starts, before the handler runs.describe(function) Optional. Returns a custom description string for the current context.examples(table) Optional. Array of example input objects for documentation.permission_scopes(string|function) Field name in schema (string) orfunction(input)returning a list of path scopes that need write permission. Declaring it is what puts the tool in front of the permission prompt, and it requirespermission.permission(string|table) The capability the tool reaches: "fs_read", "fs_write", "net", "run", or "env". Your plugin must hold it, and so must any plugin that pre-approves the tool, hooks it, or hands it to a session. Withoutpermission_scopesthe tool never prompts, the right declaration for read-only tools. Pass{}when the handler calls no guardedmakifunction and no other tool. Such a tool needs no grant and is free to hand to a session. It cannot havepermission_scopesormutable_path, and older maki versions refuse it, so setmin_maki_version. Leavingpermissionout costs those plugins every permission exceptagentandinput.mutable_path(string) Schema field name (type: string) for the primary path the tool writes. Required withpermission = "fs_write". Declaring it is what gets the tool, from the dispatcher and never from the handler: serialization of concurrent calls on that file, the stale-read rejection, the plan-mode block, and the permission boundary check.start_annotation(string|table) Schema field used to annotate the start header with a count (string) or timeout ({ field, kind="timeout" }).needs_background(boolean) Offer the tool only to a model that can move a call to the background itself: the main agent of a session where background tasks are on. Default: false. A schema property can set the same key to hide just that (optional) parameter. The choice is made when the session's tool list is built, and a call that names a hidden parameter still validates.
Example:
maki.api.register_tool({
name = "word_count",
description = "Count words in a file.",
kind = "read",
schema = {
type = "object",
properties = { path = { type = "string", description = "File path" } },
required = { "path" },
},
handler = function(input)
local f = io.open(input.path, "r")
if not f then return { llm_output = "file not found", is_error = true } end
local n = 0
for _ in f:read("*a"):gmatch("%S+") do n = n + 1 end
f:close()
return tostring(n) .. " words"
end,
})
maki.api.register_permission_rule()
maki.api.register_permission_rule({spec})
Declare an agent permission rule for a native tool. Use it to pre-allow (or pre-deny) tool calls on paths your plugin owns, like a storage directory outside the working dir, so the user is not prompted for them.
Rules live as long as the plugin is loaded: a reload replaces them, and a reload that registers none clears the old ones. User config and session deny rules always win over a plugin allow.
An allow is delegation, not escalation: it needs the permission the
target tool declares, so a plugin can only pre-approve what it could
already do itself. A deny needs no permission. An allow on a tool that
never prompts (permission without permission_scopes) has nothing to
pre-approve and is dropped.
Allows are checked once the plugin finishes loading, so a plugin may
pre-approve a tool it registers itself. One that does not hold up (no such
tool, a tool with no permission_scopes that is never checked, or a
permission the plugin lacks) is dropped with a warning in the log while the
rest of the plugin loads. Without the rule the call simply prompts.
Parameters:
{spec}(table) Rule specification:tool(string) Required. Native tool name (e.g. "edit", "write"). MCP tools and the "*" wildcard are not allowed.scope(string) Required. Scope pattern the rule applies to, e.g. "/abs/dir/" for a directory subtree. An allow whose pattern matches every scope ("*", "", "/*", "/**") is refused: name the paths or commands it covers. A deny may cover everything.effect(string) Optional. "allow" (default) or "deny".
Example:
maki.api.register_permission_rule({
tool = "write",
scope = notes_dir .. "/**",
})
maki.api.register_command()
maki.api.register_command({spec})
Register a slash-command that appears in the user input bar.
Slash commands let the user trigger plugin actions by typing /name in the
input. Use them for interactive workflows that do not need the model, like
browsing memory files or toggling settings.
Parameters:
{spec}(table) Command specification:name(string) Required. The command name (e.g. "/hello"; a leading slash is added when missing).description(string) Optional. Short description shown in the command palette.nargs(integer|string) Optional. How many arguments the command takes, spelled like nvim's nargs: 0 (default), 1, "?" (zero or one), "*" (any number), or "+" (one or more). An argument is a whitespace separated word. Type more than allowed and the command quietly stops matching: the input goes to the model as a normal message. Only the upper bound is checked, so with "+" you still need to handle an emptyopts.argsyourself.handler(function) Required. Called when the user runs the command, with one opts table:opts.argsis the raw argument string (whitespace kept, may be empty) andopts.fargsis the same split into words.
Example:
maki.api.register_command({
name = "/hello",
description = "Say hello",
handler = function()
maki.ui.flash("Hello from my plugin!")
end,
})
maki.api.register_prompt_hint()
maki.api.register_prompt_hint({spec})
Add a piece of text to an aggregate prompt slot. Multiple plugins can each contribute to the same slot, and all contributions are concatenated.
Good for things like tool usage guidelines or extra context that should
appear alongside other plugins' hints. If you need to own the whole slot
(e.g. identity or tone), use set_prompt instead.
Throws if you pass a singleton slot name.
A function content is called before every run. Its first value goes in
the system prompt, and later changes reach the model as a context update
until the next compaction. maki -p, the SDK and ACP call it once, at
startup.
Parameters:
{spec}(table) Hint specification:slot(string) Required. Aggregate slot name (e.g. "tool_usage", "conventions").content(string|function) Required. Static text, or afunction(ctx)that returns a string. Max 1 MiB.ctx.session_idis the session whose prompt is being built.ctxis nil with no session (startup, ACP).prompt(string|string[]) Optional. Restrict to specific prompt ids (e.g. "system").
Example:
maki.api.register_prompt_hint({
slot = "tool_usage",
content = "- Prefer **grep** over reading entire files.",
})
maki.api.register_options()
maki.api.register_options({spec})
Declare the options your plugin accepts under plugins.<name> in
maki.setup, and get back what the user set merged with your defaults.
Call it once, at the top level of your plugin file.
An unknown key, a wrong type, or a value below min fails the plugin
load with a clear message, so users catch typos right away. Bad specs
fail the load too. The specs also feed the generated configuration docs.
Parameters:
{spec}(table) Map of option name to a spec table:default(boolean|number|string) Optional. Used when the user sets nothing. Its Lua type becomes the option type.type(string) Required when there is no default: "boolean", "integer", "number", or "string".min(number) Optional. Minimum accepted value, numeric options only.desc(string) Required. One line shown in the configuration docs.
Returns: (table) Merged options: the user's value where set, otherwise the default, or nil when neither exists.
Example:
local opts = maki.api.register_options({
timeout_secs = { default = 120, min = 5, desc = "Kill the command after this many seconds." },
max_output_lines = { type = "integer", desc = "Override agent.max_output_lines for this tool." },
})
maki.api.set_prompt()
maki.api.set_prompt({spec})
Replace a complete prompt or one named section. Section replacements
preserve additive hints registered through register_prompt_hint.
Omit slot to replace a whole template; this requires one explicit prompt
ID. A replacement inserts section defaults, hints, and instructions only
through explicit {{section}} and {{instructions}} markers. An empty
string clears a template or section. The alphabetically last plugin wins,
and its last registration wins within that plugin. Unload removes its values.
Prompt IDs: system, research, general, and plan.
Sections: identity, tone, tool_usage, efficient_tools, conventions,
after_instructions, objectivity, and completion.
Identity and tone are available in system, research, and general prompts.
Sections target the main agent when prompt is omitted. Only identity and
tone accept a function, called before every run with ctx as in
register_prompt_hint. Its first value goes in the system prompt. Later
changes reach the main agent as a context update.
Other replacements require static strings.
A known section missing from the resolved template is ignored, with a warning
for explicit prompt targets.
Parameters:
{spec}(table) Prompt replacement:slot(string) Optional. Named section, e.g. "identity", "tone", "conventions".content(string|function) Required. Replacement text, including empty text. Max 1 MiB. Only identity and tone accept functions.prompt(string|string[]) Optional for sections; defaults to "system". A whole replacement requires one explicit prompt ID.
Example:
maki.api.set_prompt({
prompt = "system",
slot = "conventions",
content = "State uncertainty and cite your evidence.",
})
maki.api.set_prompt({
prompt = "system",
content = "You help analyse information.\n{{tool_usage}}",
})
maki.api.get_tools()
maki.api.get_tools({opts?})
Return a list of all registered tools. Useful for building UI that shows available tools or for checking which tools are enabled.
Each entry has the tool's name, schema, audiences, and an enabled flag.
Describe callbacks are not invoked (the static description is used).
permission is as in get_tool.
Parameters:
{opts?}(table?) Options:config(table) Optional config table with adisabled_toolsstring[] field used to compute theenabledflag on each entry.
Returns: (table[]) Array of tool entries: { name, schema, audiences, kind?, permission?, enabled }.
Example:
local tools = maki.api.get_tools()
for _, t in ipairs(tools) do
print(t.name, t.enabled)
end
maki.api.get_tool()
maki.api.get_tool({name})
Look up a single tool by name. Returns its metadata table or nil if the
tool does not exist. For Lua-registered tools the returned table also
includes header and restore handle functions (wrapped so they never
throw).
tool_search and MCP tools (server__tool names) never enter the
registry. For them the table holds only name, header, and the
format ("plain" or "markdown") of the standalone call, enough for a
composing tool like batch to draw a child the same way. Any
server__tool shaped name resolves whether or not a server offers it,
so this is not an existence check for MCP tools.
background_params lists the parameters marked needs_background,
which only a session that can move calls to the background sees.
permission lists what the tool reaches, shaped like capability from
get_slots: { "fs_read" }, {} for nothing, or nil when the tool
declared none (MCP tools and tool_search included).
Parameters:
{name}(string) Exact tool name.
Returns: (table|nil) Tool entry with fields { name, schema, audiences, kind?, permission?, background_params?, header?, restore?, format? }, or nil if not found.
Example:
local t = maki.api.get_tool("bash")
if t then
print("bash audiences:", table.concat(t.audiences, ", "))
end
maki.api.run_command()
maki.api.run_command({cmdline})
Runs a slash command by name, exactly as typing it in the input would.
Works for built-ins, custom /project: and /user: commands, MCP
prompts, and commands other plugins registered.
Use it to alias a command you like under a name you prefer, instead of
reimplementing what it does. See maki.ui.action for the same idea
applied to keybound UI actions.
Pass the whole command line, arguments included: "/cd ~/src". The
leading slash is optional. Names match exactly apart from case, so a typo
reports an error instead of running the closest command, and a cycle of
aliases stops with one too.
This returns as soon as the command has been dispatched, not when it
finishes, so aliasing something long-running like /compact does not
block your handler.
A command outside the calling plugin's grants returns an error, and a few only run when you type them. Commands lists what each one needs.
Parameters:
{cmdline}(string) Command line, e.g."/new"or"/cd ~/src".
Returns: (boolean|nil, string|nil) true once dispatched, or nil and an error message for an unknown or denied command.
Example:
-- /resume as an alias for the built-in session picker:
maki.api.register_command({
name = "/resume",
description = "Alias for /sessions",
handler = function()
local ok, err = maki.api.run_command("/sessions")
if not ok then
maki.ui.flash("could not run /sessions: " .. err)
end
end,
})
maki.api.create_autocmd()
maki.api.create_autocmd({event}, {opts})
Listen for one or more events. Returns an id you can pass to
del_autocmd later to remove the listener.
Built-in events fired by the host: "TurnStart", "TurnEnd",
"TurnError", "TurnComplete", "ToolStart", "ToolDone",
"AutoCompacting", "CompactionDone", "PlanReady", "SessionReset", "SessionEnd",
"SessionFocusChanged", "SessionStatusChanged", "SessionTitleChanged",
"SessionCwdChanged", "TaskStatusChanged", "TaskStopped", "TaskFocusChanged", "ModelChanged", "InputChanged",
"ModeChanged" and "FileIndexReady". Plugins can also fire their own
events with exec_autocmds.
Every host event carries data.session_id except "FileIndexReady",
which is about a directory rather than a session, and "ModeChanged",
since the mode is the same in every session. For "SessionReset" and
"SessionEnd" that is the session being left behind, the other events
name the session now running or focused. What each event adds:
"ToolStart","ToolDone":data.tool_idanddata.tool."ToolDone"addsdata.is_erroranddata.bytes, the size of the text the model reads. A call that ran also carriesdata.duration_msanddata.input, the input after everytool.*.inputlayer. A call that never ran, like a cancelled one, has neither."TurnStart":data.text, the message that started the turn."TurnEnd":data.reason("finished","max_tokens","max_turns","cancelled", or"dropped"when anagent.user_messagelayer refused the message),data.usage(four token fields, cache included),data.cost,data.list_cost,data.context_size,data.context_window, anddata.num_turns(model round-trips the turn took).list_costis the un-subsidised list price andcostis the real bill, so a budget plugin charges against whichever one it wants."TurnComplete":data.context_sizeanddata.context_windowafter each model response, before its tool calls run. Use it to act mid-turn, before"AutoCompacting".data.context_sizeis absent when unknown. A subagent's response carries its own sizes plusdata.id, its task id, whichmaki.session.notifytakes astaskto reach that subagent. To watch only the main context, skip events that have anid."AutoCompacting":data.context_sizeanddata.context_windowat trigger time."CompactionDone":data.context_size_before,data.context_size_after,data.context_window, anddata.summary, the text that replaced the history."PlanReady":data.path, the absolute path of the plan file the agent just wrote. Fires once per draft. Plan state is per session, so passdata.session_idtomaki.plan.read."SessionFocusChanged":data.previous_session_id, absent on the first focus at startup."SessionStatusChanged":data.status("working","needs_input", or"idle"),data.title, anddata.focused(boolean). A session stays"working"while a background task it waits on still runs."SessionTitleChanged":data.titleanddata.focused(boolean), when the title changes (rename or auto-generation)."SessionCwdChanged":data.cwd, the session's new working directory, when/cdchanges it."TaskStatusChanged":data.id,data.name, anddata.status("working","idle","done","error", or"cancelled"), when a subagent starts or changes status. A task a plugin opened withmaki.agent.sessioncarriesdata.plugin, and"idle"is such a task between prompts. A task that comes back from disk already finished stays quiet, so reloading a session does not replay old tasks."TaskStopped":data.id, when the user stops a task with Esc in its tab or throughmaki.task.stop. A plugin task carriesdata.plugin, and by then it is already gone frommaki.agent.list()."TaskStatusChanged"compares tasks once per frame, so it can miss a task that opened and stopped in the same frame. This event never does, so an owner can rely on it to drop work it still has queued."TaskFocusChanged":data.id, the task now on screen ("main"or a subagent's id, whatctx:task_id()reports inside a tool). Fires for the chat cycling keys,maki.task.focus, and a session switch that lands on another task."ModelChanged":data.modelin the shapemaki.model.getreturns, plusdata.previous_spec. Picking the model already in use stays quiet, and so does startup."InputChanged":data.text,data.cursor,data.anchor,data.versionanddata.session_id, asmaki.ui.inputreports them.data.cursor_onlyis true when only the cursor or the selection moved.data.sourcenames the plugin whosemaki.ui.input_editmade the only change since the last"InputChanged", and is nil otherwise, so a handler can skip its own edits. A package goes by its package name, andinit.luacode by"global/init.lua"or"project/init.lua". Fires at most once per screen redraw, and again for the input of a tab that takes focus. Marks alone do not fire it, so a handler can callmaki.ui.input_decoratewithout looping."ModeChanged":data.old_modeanddata.new_mode, each"n"or"i". Fires whenevermaki.fn.mode()changes: onmaki.ui.set_mode, and when the chat input gains or loses the keyboard, as when a picker opens. Use it to draw a mode indicator. Like"InputChanged", it fires only with a UI."FileIndexReady":data.root, the absolute directory that was walked,data.files, how many paths the walk left, anddata.crashedanddata.truncated, the two ways that list is not the whole tree. Fires once per walk that ends, whatevermaki.fs.fuzzy_filesor theCtrl+Spicker started it, so a plugin ranking files asks again instead of polling. A walk cancelled before it ended stays quiet.data.rootis absent for a directory with no UTF-8 spelling, and so is therootof the call that asked for the walk, so a plugin matching the two takes an event without a root as a reason to ask again. Asking again only ever re-reads the root the plugin passed.
Conversation content needs the session_read permission. Without it a
host event still arrives, carrying only its metadata fields:
"TurnStart" without data.text, "ToolDone" without data.input,
"CompactionDone" without data.summary, and "InputChanged" without
data.text. Maki warns once per plugin and event, naming what was left
out. Events a plugin fires under its own names arrive as fired.
A subagent's run fires only "TurnComplete", never tool or other turn
events. "TurnEnd" fires once per turn of the main session. A manual /compact fires no "TurnEnd", only the
"TurnComplete" of its summary request.
Drivers are not all caught up. "TurnStart" and "PlanReady" come from
maki-ui only. maki-acp runs the agent on its own loop and does not
call the dispatcher yet, so plugins loaded under ACP receive no turn
events. Everything else fires under maki -p and sdk mode as well.
"SessionEnd" is the teardown signal: it fires first so handlers can
still inspect or stop the session's jobs, then session-owned jobs are
reaped. data.reason names the path it came from: "reset" (TUI
/new), "load", "delete" (tab closed), "shutdown", "reload"
(/reload is rebuilding the plugin host, and the session carries on in
the new one), "replaced" (an ACP client took the session's place), or
"completed" (a headless run finished).
On "shutdown", "reload", "replaced", and "completed" the host is
already tearing down, so the UI is detached (maki.fn roundtrips fail
right away) and every handler shares one grace period. data.deadline_ms
is how much of it is left at dispatch, so write state out with maki.fs
and do not park. On the other reasons nothing waits and data.deadline_ms
is nil.
"SessionReset" stays TUI-only (/new) and fires on the same path as
"SessionEnd" with reason = "reset".
Jobs started inside a callback die with the dispatch unless you await
them there (jobwait) or hand them to a session
(scope = { session = ... }).
Parameters:
{event}(string|string[]) Event name or list of names.{opts}(table) Options:callback(function) called with an ev table{ id, event, match, data }.once(boolean) remove the handler after it fires once (default false).pattern(string|string[]) only fire when the pattern matches."*"matches everything. Omit to match all.
Returns: (integer) Autocmd id.
Example:
local id = maki.api.create_autocmd("TurnEnd", {
callback = function(ev)
print("turn ended: " .. ev.event)
end,
})
maki.api.del_autocmd()
maki.api.del_autocmd({id})
Remove a previously registered autocmd. Does nothing if the {id} does not exist.
Parameters:
{id}(integer) Id returned bycreate_autocmd.
Example:
maki.api.del_autocmd(id)
maki.api.exec_autocmds()
maki.api.exec_autocmds({event}, {opts?})
Fire one or more events manually. Every matching autocmd callback runs to completion before this function returns.
A handler may suspend, so this call may too.
Parameters:
{event}(string|string[]) Event name or list of names to fire.{opts?}(table?) Options:pattern(string) passed to callbacks asev.match.data(any) arbitrary value passed asev.data.
Example:
maki.api.exec_autocmds("MyEvent", {
pattern = "init",
data = { msg = "hello" },
})
maki.api.register_action()
maki.api.register_action({name}, {callback}, {opts?})
Registers {callback} as an action that maki.ui.action runs. This is
how a user's init.lua reaches your plugin, since require only sees
the calling plugin's own files.
The action is named after your plugin: register_action("accept", ...)
in a plugin installed as completion registers "completion.accept". In
the global or project init.lua the prefix is user, like
"user.paste_plain". A plugin named user cannot register actions, so no
plugin can replace the ones a user's keys call.
The callback runs as your plugin, inside the caller's key handler, and
maki.ui.action returns its value. Return true when it handled the
request, and false or nothing so the caller can try something else.
Registering a name again replaces the callback, and the action goes away
when your plugin unloads. When both init.lua files register a name, the
project one wins until it is gone.
opts.capability is the price of the action: the permissions a caller
must hold. Without it, the price is every permission your plugin holds.
With {}, any caller gets in, and the callback holds no permission. A
caller that falls short gets nil and an error naming the missing
permission.
The price also caps the callback, whoever calls it, so list everything
it uses. A call that needs a permission outside the price fails as it
would in a plugin without that permission. The cap covers the tasks,
timers and jobs the callback starts, and the tools, permission rules,
slot layers and actions it registers. Keymaps and autocmds it sets run
later with all your grants. Code of other plugins that runs meanwhile,
like their autocmds, keeps its own grants. For example,
completion.accept writes file paths into the input that Enter then
sends, so it lists fs_read, input, session_read, agent and
session_write.
Also bind a default key for users who do not compose keys, preferably an Alt chord, since your binding shadows theirs on the same key.
Throws when capability lists a permission your plugin does not hold, or
when {name} is empty or has a ..
Parameters:
{name}(string) The name after the prefix, like"accept".{callback}(function) Called with no arguments. Returntruewhen handled.{opts?}(table|nil){ capability = { "fs_read", ... } }: what a caller must hold. Default: every permission your plugin holds.
Returns: (string) The full name to pass to maki.ui.action, like "completion.accept".
Example:
-- Writes a file path into the input, so a caller must hold what that takes:
maki.api.register_action("accept", function()
if not Menu.open() then return false end
Menu.accept()
return true
end, { capability = { "fs_read", "input", "session_read", "agent", "session_write" } })
maki.api.declare_slot()
maki.api.declare_slot({name}, {default}, {opts?})
Create a named extension point owned by your plugin. You provide a
{default} function, and other plugins can wrap it with layers using
set_slot. The returned callable runs the full chain: outermost layer
first, then inward, ending at {default}.
{opts} prices what a layer from another plugin pays to steer your chain.
You set it, because you are the only one who knows what your default does
with the arguments it is handed. Pass { capability = { "net" } } to
charge the permissions you name, all of them at once; { capability = {} }
to let anyone layer for free, which is the honest price for a slot whose
arguments are inert; or leave {opts} out to charge every permission. You
can only name permissions your own plugin holds.
Throws if another plugin already owns a slot with the same {name}, or
if {name} starts with "tool.", "ui.", "agent.", or "permission.",
which the host fires itself.
The name stays yours across an unload: nobody else can take it over, or
re-declare it cheaper, while maki runs.
The chain is async: the default and every layer may park (maki.fs.*,
maki.fn.jobwait, maki.agent.call_tool, ...), and so does the
returned callable. Call it from a tool handler, a command, or an
autocmd, rather than from a header or restore function, which
cannot wait. The chain runs in your task, so cancelling the caller
cancels the layers it is waiting on.
Parameters:
{name}(string) Unique slot name, e.g."myplugin.render".{default}(function) Default implementation, called when no layers wrap it.{opts?}(table|nil){ capability = { "net", ... } }: what a layer from another plugin pays.
Returns: (function) Callable that dispatches through all layers.
Example:
-- anyone may layer this one: it only uppercases the text it is given
local render = maki.api.declare_slot("myplugin.render", function(text)
return text:upper()
end, { capability = {} })
print(render("hello")) -- HELLO
maki.api.set_slot()
maki.api.set_slot({name}, {wrapper})
Add a layer around an existing (or future) slot. Layers wrap the
default from the outside in. Each layer receives prev as its
first argument. Call prev(...) to continue down the chain.
Calling prev more than once throws.
You can call this before the owner runs declare_slot. The layer
is queued and attached when the slot is declared.
A layer may park, and one that throws is skipped: the chain continues
as if it had returned prev(...) untouched, so a broken layer never
takes the seam down with it.
Layers wrap in registration order, so the last one registered runs first and sees the value before the others do.
Maki fires two slots around the plan form, both with
ev = { path, session }. ui.plan_form.actions asks for the form's
menu, and ui.plan_form asks whether the form opens at all. Both are
documented under maki.plan.
Maki fires two slots per tool itself: tool.<name>.input before
permissions look at the call, and tool.<name>.output on the text it
produced. Both take function(prev, value, ctx) and answer with a
table to replace the value, nothing to leave it alone, or
nil, reason to stop the call. An input layer can also answer
value, { ask = reason } to make the user approve the call. Name the
tool * (tool.*.input) to wrap every tool. What a layer costs is in
the Hooks price table.
The agent loop fires agent.user_message, agent.stop,
agent.compact.before, and agent.compact.prepare, with the same
contract. Wrapping one costs agent, session_read and session_write,
since every slot can hand a layer text the user or the model wrote, and a
layer steers what happens next. See Hooks.
permission.prompt fires where the permission prompt would show, with
the prompt as its default. A layer takes function(prev, req, ctx) and
answers { decision = "allow" } or { decision = "deny", guidance = … },
or passes the call on with prev(req, ctx). A verdict decides that one call
and records no rule, and an escalated call (ask) is never offered to a
layer. It costs what a layer on the same call does. See
Hooks.
Wrapping a slot another plugin declared steers a chain that plugin's
callers trust, so it costs whatever the owner priced it at in
declare_slot: the capabilities it named, every permission if it named
none, or nothing at all if it declared its arguments inert. Layering a slot
you declared yourself is free. Like the tool.* slots, this is decided
when the chain fires: the call skips a layer that is not entitled and
carries on, and a reload that changes what you hold takes effect on the
next call. A layer set inside an
action callback is weighed against the
action's price too.
Parameters:
{name}(string) Slot name to wrap.{wrapper}(function) Layer:function(prev, ...). Callprev(...)to continue.
Example:
maki.api.set_slot("myplugin.render", function(prev, text)
return prev("[" .. text .. "]")
end)
maki.api.get_slots()
maki.api.get_slots()
List all known slots and their current state. Useful for debugging which plugins own or wrap each slot.
capability is the list of permissions a layer from another plugin pays,
and is absent on a slot whose owner named no price, which costs every
permission.
Returns: (table) Map of slot name to { owner, declared, fillers, capability }.
Example:
for name, info in pairs(maki.api.get_slots()) do
print(name, info.owner, info.declared)
end
maki.plan
Plan-mode surface for plugins.
Read the plan, and shape the plan form by layering the two slots maki
fires around it. Plan state is per session, so every call takes an
optional session and defaults to the focused tab.
ui.plan_form.actions is the menu. The default answers with the
built-in rows, each { id, label, desc, action }, and a layer
appends, reorders or drops them before returning the list. Every row
needs an id no other row uses, since that is how a later layer finds
it. Anything past the 32nd row is dropped.
A row carrying a handler has that function called on the Lua thread
with { session, path, parallel } when the user picks it. The row's
action runs after the handler returns, unless the handler returned
false or failed, so copying a built-in row and adding a handler
keeps the built-in outcome. Drop the action to replace it.
ui.plan_form is the form itself. A layer that answers false keeps
it closed and renders the plan however it likes.
Layering either slot costs every permission, the price of steering a call whose reach nobody declared: a row decides what pressing Enter does, up to a build-mode turn with every tool behind it.
Unloading your plugin hands the form back and reaps its row handlers.
-- A row of your own, next to the built-in ones:
maki.api.set_slot("ui.plan_form.actions", function(prev, ev)
local rows = prev(ev)
table.insert(rows, {
id = "commit_and_implement",
label = "Commit and implement",
desc = "Commit the plan file first, then implement it",
handler = function(opts)
maki.fn.system({ "git", "commit", "-am", "plan" })
maki.session.set_mode("build", { session = opts.session })
maki.session.prompt("Implement " .. opts.path, { session = opts.session })
end,
})
return rows
end)
-- Render the plan yourself for as long as this plugin is loaded:
maki.api.set_slot("ui.plan_form", function(prev, ev)
local plan = maki.plan.read({ session = ev.session })
return false
end)
maki.plan.read()
maki.plan.read({opts?})
Read the current plan state. Returns { mode, path, content, ready }:
modeis"plan"or"build".pathis the absolute plan path once the session has one, elsenil.readyistrueonce the agent has written the plan file.contentis the file contents,nilwhen the plan is not ready or the read failed.
Requires the session_read plugin permission.
Parameters:
{opts?}(table?)session(string?) Session id, defaults to focused.
Returns: (table|nil, string|nil) Plan snapshot table, or nil and an error.
Example:
local plan, err = maki.plan.read({ session = id })
if plan and plan.ready then
print(plan.path, plan.content)
end
maki.agent
Subagent primitives for plugins that need to talk to an LLM.
This module gives you the building blocks: resolve which model to use, build a system prompt, list available tools, call a tool directly, or open a full session with its own conversation history.
Policy like retries, validation, and concurrency lives in the calling plugin, not here.
local tools = maki.agent.tools(ctx, { audience = "general_sub" })
local sess = maki.agent.session(ctx, {
system = "You are a helpful assistant.",
tools = tools,
})
local r = sess:prompt("Hello!")
print(r.text)
sess:close()
A CI monitor for each chat session the user opens. It wakes the agent
once when CI turns red and stays quiet until CI is green again. Each
wake costs a full agent turn, and the model words the same failure
differently every round, so comparing replies would wake it every time.
SessionFocusChanged also fires after /reload, so the monitor comes
back on its own.
local tasks, failing = {}, {}
local function start(sid)
if tasks[sid] then return end
tasks[sid] = maki.async.spawn(function()
while true do
maki.async.sleep(5 * 60 * 1000)
-- Prompts are denied here, so this needs an allow rule like `gh run list *`.
local sess = maki.agent.session({
session = sid,
name = "ci-monitor",
system = "Run `gh run list -L 3`. Reply exactly OK if all runs passed, else a 3-line failure summary.",
tools = (maki.agent.tools({ session = sid, audience = "general_sub", only = { "bash" } })),
})
-- nil once the chat session is gone. SessionEnd below stops the loop.
if sess then
local r, err = sess:prompt("Check CI now.")
sess:close()
local text = not err and r.text:match("^%s*(.-)%s*$")
if text == "OK" or text == "OK." then
failing[sid] = nil
elseif text and text ~= "" and not failing[sid] then
failing[sid] = true
maki.session.notify("[ci-monitor] " .. text, { session = sid, wake = true })
end
end
end
end)
end
maki.api.create_autocmd("SessionFocusChanged", {
callback = function(ev) start(ev.data.session_id) end,
})
maki.api.create_autocmd("SessionEnd", {
callback = function(ev)
local sid = ev.data.session_id
if tasks[sid] then tasks[sid]:cancel() end
tasks[sid], failing[sid] = nil, nil
end,
})
maki.agent.resolve_model()
maki.agent.resolve_model({ctx}, {opts?})
Look up the model that the current agent is using, or pick a cheaper one. You might want a cheaper model for simple subtasks (summaries, classification) without hard-coding a model name.
The returned table has fields: id (string), tier (string),
provider (string), spec (string), assigned_tier (string?).
assigned_tier is set when the user assigned this model to that tier, and
nil for an explicit spec, the inherited model or a curated default. Mention
it in your errors, since the user may have forgotten the assignment. If an
assigned model no longer resolves, you get an error instead of another model.
Parameters:
{ctx}(LuaCtx) Agent context.{opts?}(table?) Optional fields:tier(string?) target tier, e.g."fast","mid","best". Clamped to the parent tier so you cannot escalate. Resolved bymaki.model.tier, so a/modelpick for the tier wins over the session provider's curated default.spec(string?) exact model spec string, e.g."claude-3-5-haiku-20241022". Takes precedence overtier.
Returns: (table?, string?) Model table on success, or (nil, err) on failure.
Example:
local model, err = maki.agent.resolve_model(ctx, { tier = "fast" })
if err then error(err) end
print(model.spec, model.tier)
maki.agent.system_prompt()
maki.agent.system_prompt({ctx}, {opts})
Build a system prompt from the parent's resolved prompt catalogue.
Plugin template and section replacements apply. Environment variables like
{cwd} are substituted automatically. Use this when you need a ready-made
prompt for a subagent session.
Parameters:
-
{ctx}(LuaCtx) Agent context. -
{opts}(table) Required fields:prompt_id(string) one of"research","general","system".
Optional fields:
instructions(string|boolean?) text inserted at the template's{{instructions}}marker.trueloads project instruction files.falseor nil omits them.tools(table[]?) the definitions the session will get, as returned bymaki.agent.tools. A plugin's hints are dropped when none of its tools are in it. Without it, the hints follow the config.
Returns: (string?, string?) The assembled prompt string, or (nil, err) on failure.
Example:
local prompt, err = maki.agent.system_prompt(ctx, {
prompt_id = "research",
instructions = true,
tools = tool_defs,
})
if err then error(err) end
maki.agent.tools()
maki.agent.tools({ctx}, {opts?})
Get the list of tool definitions for a given audience. Pass the result
straight into maki.agent.session() or use it to inspect what tools are
available.
A session costs what its tools reach (see maki.agent.session). To keep
only tools the plugin can pay for, filter on each tool's permission
from maki.api.get_tool, as the example does.
Without a ctx, pass session = id in opts to get the tools a
background session of that chat would have.
Parameters:
-
{ctx}(LuaCtx|table) Agent context, oroptswhen called without one. -
{opts?}(table?) Required with a ctx. Fields:session(string) only without a ctx: id of a live chat session.audience(string) tool audience filter, e.g."general","subagent","general_sub".
Optional fields:
only(string[]?) include only these tool names.except(string[]?) exclude these tool names.workflow(boolean?) use workflow-mode descriptions. Default:false.spec(string?) evaluate capability exclusions against this model spec.mcp(boolean?) describe tools as if MCP is reachable. Default:false. Match what you pass tomaki.agent.session(), or the descriptions advertise MCP tools the session cannot call.
Returns: (table?, string?) Array of tool definition tables, or (nil, err) on failure.
Example:
local defs, err = maki.agent.tools(ctx, {
audience = "general_sub",
except = { "bash", "write" },
})
if err then error(err) end
print(#defs .. " tools available")
-- Keep only tools this plugin can hand to a session. `held` is the
-- set of permission keys the plugin was granted.
local held = { fs_read = true, net = true }
local affordable = {}
for _, def in ipairs(defs) do
local perms = maki.api.get_tool(def.name).permission
local ok = perms ~= nil
for _, p in ipairs(perms or {}) do
ok = ok and held[p] == true
end
if ok then table.insert(affordable, def) end
end
maki.agent.callable_tools()
maki.agent.callable_tools({ctx})
Every tool name this context can dispatch: registry tools, MCP tools
(deferred ones included), host tools (ACP client tools, a subagent's
structured_output) and tool_search. Reach for it when you expose tools
inside a sandbox and need the names to bind. maki.api.get_tools() covers
the registry alone and has no view of the session.
The list already accounts for this session's audience, the config's
disabled_tools and the model's capabilities. Read audiences to layer
your own policy on top. A sandbox wants interpreter.
Each name shows up once, described by the tool a call would really reach, so a host tool that shadows a registry name reports its own audience rather than the shadowed one's.
Parameters:
{ctx}(LuaCtx) Agent context.
Returns: (table?, string?) Array of { name, alias?, source, audiences, schema? },
or (nil, err) on failure. source is one of "native", "local",
"mcp". alias is a safe identifier to bind, set only when name is not
one (say srv__get-docs). Dispatch name in every case. schema comes
with registry tools only.
Example:
local tools, err = maki.agent.callable_tools(ctx)
if err then error(err) end
for _, t in ipairs(tools) do
print(t.source, t.alias or t.name)
end
maki.agent.call_tool()
maki.agent.call_tool({ctx}, {name}, {input}, {opts?})
Run a tool by name and wait for the result. This is how you call built-in
tools (like read, bash, glob) from Lua without going through the LLM.
Live events (streaming output, annotations, cumulative usage) are delivered through optional callbacks while the tool runs.
Parameters:
{ctx}(LuaCtx) Agent context.{name}(string) Tool name, e.g."bash","read".{input}(table|any) Tool input (JSON-serializable). Must match the tool'sinput_schema.{opts?}(table?) Optional fields:timeout(integer?) deadline in seconds.output_mode(string?) "full" (default) returns the complete text. "compact" returns what the model would get, with output limits and RTK rewriting. Permissions and hooks apply in both modes, and hooks see the mode asctx.output_mode.on_live_buf(function?) called with aBufHandlefor each live buffer the tool publishes. Must not yield.on_annotation(function?) called with an annotation string for each annotation event. Must not yield. A call apermission.promptlayer allowed arrives as"allowed by <plugin>". Without this callback that mark goes on your own tool's row instead.on_usage(function?) called with a formatted cumulative token usage string. Must not yield.on_movable(function?) called withtruewhen the child registersctx:on_background, so the caller knows it may outlive the turn, andfalseif it loses that. Must not yield.on_task(function?) called with the task id when the child runs as a subagent, which/tasksthen lists as a task of its own. Must not yield.
Returns: (string?, string?, string?) Tool output text and its format
("markdown" or "plain", as a tool handler sets it), or (nil, err)
on failure. Instruction files the child picks up (a subdirectory AGENTS.md) are
not in the text: they land on the calling tool's own result.
Example:
local out, err = maki.agent.call_tool(ctx, "bash", {
command = "ls -la",
timeout = 10,
})
if err then error(err) end
print(out)
maki.agent.session()
maki.agent.session({ctx}, {opts?})
Create a new subagent session. The session inherits the parent model and
MCP handle unless you override them. You get back a Session object that
you can send messages to with :prompt().
This is the main way to spin up a sub-conversation with its own history and tool set.
Without a ctx, maki.agent.session({ session = id, ... }) opens a
background session. It borrows the model, permissions and MCP of the live
chat session id and is not tied to any turn. Call it and its :prompt()
from a task: a maki.async.spawn task, an autocmd callback or a tool
handler. This form needs the agent plugin permission.
Nobody can answer its permission prompts, so a call that would prompt is denied and the subagent is told why. Your rules, "allow for this session" answers and YOLO still apply, so add allow rules for what it runs (see Permissions). It always runs in build mode. While the chat is in plan mode its file-write tools are denied. Its thinking never goes above the chat's current setting.
With or without a ctx, the plugin must hold what its tools reach, because YOLO, allow rules and background sessions skip the prompt. Each tool costs:
- A declared permission (
bash:run,read:fs_read): that one. permission = {}, andlocal_tools(they run as the plugin): nothing.- No declaration (
batch,code_execution), ormcp = trueon a chat with MCP servers: every permission exceptagentandinput.
Look a tool up with maki.api.get_tool or on the Tools
page. If the plugin cannot pay, the error names each tool it cannot pay
for and the except list that leaves them out. The bundled task plugin
hands over the whole chat, so it holds every permission.
scope sets the lifetime. "task", the default, ends the session with
the task that opened it: an autocmd callback when it returns, a tool
handler with its tool call, a maki.async.spawn task when it finishes.
"session" outlives the task. Both end at :close(), when the chat
session ends (/new, closing the tab) and when the plugin unloads
(/reload). Turn ends, Esc and rewinds leave it alone. Esc on a tool
call still cancels a prompt that the tool's handler is waiting on.
A polling monitor opens one per round inside a maki.async.spawn loop.
An event-driven one opens once with scope = "session", keeps the handle
and prompts it from autocmd callbacks.
Opened by chat session id, it shows up in that chat as a task owned by
the plugin as soon as it opens: a transcript tab, a plugin field in
/tasks and maki.task.list(), "idle" before and between prompts, and
its spend in the chat's totals after each turn. Esc in its tab or Ctrl+S in
/tasks closes it, and the pending :prompt() returns "stopped by user"
rather than "cancelled", so a loop can tell the user's stop from its own
task ending and stop rather than reopen. Permission prompts stay denied even
though the task has a tab: a prompt in an unfocused tab would stall a
monitor silently, a denial reaches the plugin as an error it can handle.
Setting plugins.<name>.enabled = false stops a plugin's monitors from
the next /reload. Under maki -p and ACP there is no live chat
session, so opening one fails with "session not live". The
maki.agent overview has a full monitor.
Parameters:
{ctx}(LuaCtx|table) Agent context, oroptswhen called without one.{opts?}(table?) Required with a ctx. Optional fields:session(string) required without a ctx: id of the live chat session that owns it. Returns(nil, "session not live: <id>")once that session has ended.scope(string?) only without a ctx:"task"(default) or"session", see above.model_spec(string?) model spec string to use instead of the parent model.system(string?) system prompt. Defaults to empty.tools(table?) tool definitions array (frommaki.agent.tools()).local_tools(table?) map ofname -> specfor Lua-backed tools. Each spec requiresdescription(string),input_schema(table), andhandler(function). The handler receives the input table and must return(string)or(nil, err). Optionalaudiences(string[]) gates who may call it, the same waymaki.api.register_tooldoes. The default is the model alone, so a script cannot reach it throughcode_execution.name(string?) display name for logs and UI.audience(string?) tool audience for capability gating. Default:"general_sub".mcp(boolean?) give the session MCP tools. Their definitions are injected each turn (deferred behindtool_search), so do not put MCP definitions intools. Default:false.thinking(string|integer?) thinking mode:"off","adaptive", an effort level ("minimal","low","medium","high","xhigh","max"), or a budget integer (token count). Inherits the parent setting if omitted, and is capped at it otherwise.fast(boolean?) use fast mode. Inherits parent setting if omitted.
Returns: (Session?, string?) Session handle, or (nil, err) on failure.
Example:
local tools = maki.agent.tools(ctx, { audience = "general_sub" })
local sess, err = maki.agent.session(ctx, {
system = "You are a research assistant.",
tools = tools,
name = "researcher",
})
if err then error(err) end
-- Close before handling the error, so no path leaves the session open.
local result, prompt_err = sess:prompt("Summarize this file.")
sess:close()
if prompt_err then error(prompt_err) end
maki.agent.list()
maki.agent.list({opts})
List the sessions plugins opened on a chat session without a ctx, see
maki.agent.session.
Each entry has these fields:
id(string) Session id.session(string) Chat session it belongs to.plugin(string) Plugin that opened it.name(string) Name given at open.status(string)"working"while a:prompt()runs a turn or waits on calls moved to the background, otherwise"idle".started_at(integer) Unix seconds.cost(number?) Dollars billed so far, updated after each turn. nil until a priced turn ends.
Parameters:
{opts}(table) Required fields:session(string) id of the chat session.
Returns: (table?, string?) Array of entries, or (nil, err) on failure.
Example:
for _, s in ipairs(maki.agent.list({ session = id })) do
print(s.plugin, s.name, s.status, os.time() - s.started_at)
end
maki.agent.Session
A subagent session with its own conversation history.
Create one with maki.agent.session(), then send messages with
:prompt(). The session remembers previous turns, so you can have
a multi-step conversation. :send() nudges a prompt that is still
running.
Always call :close() when you are done, on error paths too. The
garbage collector is a fallback that may never run while the VM sits
idle, so a session you only drop can stay open for the rest of the run.
Session:prompt()
Session:prompt({message})
Send a message to the subagent and wait for its full response. The agent loop runs to completion, calling tools as needed. Conversation history is kept across calls, so you can have a multi-turn conversation.
The returned table has fields: text (string), duration_ms (integer),
input_tokens (integer), output_tokens (integer). text is an empty
string when the subagent produced no text block (e.g. it only called
tools).
A tool call the user moves to the background (Ctrl+B in the session's tab)
keeps the prompt waiting. When the call finishes, the subagent gets its
result and runs another turn, and text is that last turn's. Closing the
session, or the end of the task that opened it, stops such calls.
Parameters:
{message}(string) User message to send.
Returns: (table?, string?) Result table on success, or (nil, err) on
failure. A run cut short after streaming some text hands you both: the
error and a { text = <what it streamed> } table. "cancelled" means the
task that opened or prompted the session ended. "session closed" means
:close() ended it. "stopped by user" means Esc in its tab stopped it,
and "stopped by parent agent" that the model stopped the background task
it runs in. Every later prompt answers the same.
Example:
local r, err = sess:prompt("What files are in this project?")
if err then error(err) end
print(r.text)
print(r.input_tokens .. " input, " .. r.output_tokens .. " output tokens")
Session:send()
Session:send({message}, {opts?})
Hand the subagent a message without waiting, delivered the same way as a
message typed in its tab. A running :prompt() picks it up at its next
turn boundary, once the current reply and its tool calls finish, and the
model reads it as an interrupt from its parent, not the user. The tab
draws it when it lands. Messages sent in a burst land together.
With no prompt running, or one already past its last turn, the message
waits. The next :prompt() sends it in the same request as its own
message, just before it, so the first reply already reads it.
With interrupt, a running :prompt() does not wait for the turn to end,
nor for moved calls. The reply stops and running tools are cancelled (bash
returns what it printed so far). The subagent then reads the message and
carries on with its history intact, and :prompt() returns its answer as
usual. If an agent.user_message layer drops the message, the subagent
picks up the cut work instead. With no prompt running, the message waits
like any other.
Parameters:
{message}(string) Message to deliver.{opts?}(table?) Optional fields:interrupt(boolean?) cut the running turn short. Default:false.
Returns: (boolean?, string?) true, or (nil, err) when the session takes
no more messages. The errors are the ones :prompt() refuses with. true
means queued, not delivered: a message still waiting when the session
closes is dropped.
Example:
-- From another task, while `sess:prompt()` is still running.
local ok, err = sess:send("New finding: the bug is in parser.rs, focus there.")
if not ok then maki.log.warn(err) end
-- Stop a subagent heading the wrong way, mid tool call.
sess:send("Stop, the bug is in lexer.rs, not parser.rs.", { interrupt = true })
Session:close()
Session:close({result?})
Close the session and flush its history back to the parent agent. Calling it more than once is safe.
Close on every path, error paths included. Dropping the session instead leaves the work to the Lua garbage collector, which may never run while the VM sits idle, and the subagent's event relay stays alive until it does.
Close cancels a running prompt before waiting to flush its history. That
prompt returns "session closed" and any partial text.
{result} tells headless clients how the subagent ended and what it found.
Parameters:
{result?}(table?){ llm_output, is_error }, the shape a tool handler returns.
Session:id()
Session:id()
The task id of this session. A session opened by chat session id goes by
this id in maki.task.list() and the "TaskStopped" event, so a plugin
can tell which of those are its own.
Returns: (string) Session task id.
maki.async
Tools for running things concurrently in Lua plugins.
run starts a background task that ends with its caller, and spawn
one that lives as long as the plugin. gather and join run several
functions at once, and semaphore limits how many. await and wrap
turn callback APIs into coroutine calls.
local results = maki.async.gather({
function() return fetch("a.txt") end,
function() return fetch("b.txt") end,
})
maki.async.run()
maki.async.run({fn}, {on_finish?})
Start {fn} as a background task without waiting for it. Pass
{on_finish} to get the result. The task stops when its caller ends, or
after 60 seconds. A tool handler's task can outlive the reply: it runs
until the turn ends, or until the call is stopped if it was moved to the
background. For work that outlives the caller, use maki.async.spawn.
Parameters:
{fn}(function) Zero-argument function to execute.{on_finish?}(function?) Optional callbackfunction(err, result). Called once {fn} completes.
Example:
maki.async.run(function()
local data = expensive_fetch()
process(data)
end)
maki.async.spawn()
maki.async.spawn({fn})
Run {fn} in a task that lives as long as your plugin, such as a repeating timer or a connection opened at load.
The task has no deadline and outlives the call that started it, so a
tool handler can spawn it and return. It ends when {fn} returns or
raises, when you call task:cancel(), or when the plugin unloads.
Errors are logged and flashed with the plugin name.
Spawned at the top level of a plugin file, it starts after the plugin
loads. It does not keep maki alive: maki -p drops it on exit.
Code that runs 5 seconds without yielding is still stopped. See
maki.async.sleep.
Parameters:
{fn}(function) Zero-argument function to run.
Returns: (maki.async.Task) Handle with :cancel().
Example:
local task = maki.async.spawn(function()
while true do
maki.async.sleep(2000)
report()
end
end)
task:cancel()
maki.async.sleep()
maki.async.sleep({ms})
Suspend the calling task for {ms} milliseconds. Other tasks and the UI keep running. Cancelling the task ends the sleep early with an error.
All plugins share one Lua thread. Code that runs for 5 seconds without
yielding is stopped with an error. sleep(0) lets every other ready
task run once, then returns. Call it periodically in long loops.
A repeating timer is a sleep loop inside maki.async.spawn. For a
one-shot timer that outlives the tool call, such as a toast that
dismisses itself, use maki.defer_fn.
Parameters:
{ms}(integer) Milliseconds to wait. Negative values raise an error.
Example:
maki.async.spawn(function()
while true do
poll()
maki.async.sleep(5000)
end
end)
-- A long loop that keeps the rest of maki responsive:
for i, line in ipairs(lines) do
if i % 1000 == 0 then
maki.async.sleep(0)
end
process(line)
end
maki.async.await()
maki.async.await({argc}, {fn}, {...})
Turn a callback-based function into a normal call you can use in a coroutine. It calls fn(..., callback), inserting the callback at position {argc}, then suspends your coroutine until the callback fires. You get back whatever the callback was called with.
Parameters:
{argc}(integer) Total number of positional arguments {fn} expects (including the callback). Must be >= 1.{fn}(function) Callback-based function to call.{...}(any) Extra arguments forwarded to {fn} before the injected callback.
Returns: (...) Values passed by the caller to the injected callback.
Example:
local result = maki.async.await(2, http.get, url)
maki.async.wrap()
maki.async.wrap({argc}, {fn})
Create a coroutine-friendly wrapper around a callback-based function. The wrapper calls maki.async.await for you, so you can use the result like a normal function call.
Parameters:
{argc}(integer) Callback position, forwarded tomaki.async.await.{fn}(function) Callback-based function to wrap.
Returns: (function) Wrapped function you can call like a normal function.
Example:
local get = maki.async.wrap(2, http.get)
local body = get(url)
maki.async.join()
maki.async.join({max_jobs}, {fns})
Run all functions in {fns} with at most {max_jobs} going at once. Waits until every function has finished. Unlike gather, this does not return individual results.
Parameters:
{max_jobs}(integer) Maximum number of functions running at the same time.{fns}(table) Array of zero-argument functions to execute.
Example:
maki.async.join(4, {
function() process(files[1]) end,
function() process(files[2]) end,
function() process(files[3]) end,
})
maki.async.gather()
maki.async.gather({fns})
Run all functions in {fns} at the same time and collect their results.
Unlike join, this gives you back the return value (or error) from each
function. The results are in the same order as the input.
Each entry in the result array has ok (boolean), and either value
(on success) or err (string, on failure).
Parameters:
{fns}(table) Array of zero-argument functions.
Returns: (table) Array of result tables, one per function.
Example:
local results = maki.async.gather({
function() return fetch("a.txt") end,
function() return fetch("b.txt") end,
})
for i, r in ipairs(results) do
if r.ok then print(r.value) else print("error: " .. r.err) end
end
maki.async.semaphore()
maki.async.semaphore({n})
Create a counting semaphore that allows at most {n} concurrent permits. Use this to limit how many tasks hit a resource at the same time.
Parameters:
{n}(integer) Maximum number of concurrent permits. Values below 1 are clamped to 1.
Returns: (maki.async.Semaphore) A new semaphore.
Example:
local sem = maki.async.semaphore(5)
-- each task acquires a permit before doing work
local permit = sem:acquire()
do_work()
permit:release()
maki.async.on_cancel()
maki.async.on_cancel({fn})
Register {fn} to run as soon as the current task is cancelled or hits
its deadline, without waiting for whatever it is doing to finish. Use
it to paint the cancelled state: a handler waiting on children
(gather, call_tool) stays parked until they wind down, so anything
after the wait is too late to reach the screen.
The callback receives the reason ("cancelled", "timeout", or
"stopped" when the model's task_stop ended a background task) and may
still call ctx:finish; the host prefers that reply over the generic
cancelled/timeout error. Mark it is_error = true and end it with a
marker, so the model knows the output it gets is cut short.
The callback runs outside your coroutine, so it must not yield. It fires at most once, immediately if the task is already cancelled. An error inside it is logged and never reaches your handler, and the other hooks still run.
Parameters:
{fn}(function) Function to run on cancel; receives the reason string.
Example:
maki.async.on_cancel(function(reason)
view:append({ { reason, "tool_error" } })
ctx:finish({ llm_output = partial .. "\n[cancelled; output is partial]", is_error = true })
end)
maki.async.gather(children)
maki.async.Semaphore
A counting semaphore for limiting how many tasks run at once.
Create one with maki.async.semaphore(n), then call :acquire() to
get a permit before doing work. If the task is cancelled, the acquire
is cancelled too.
Semaphore:acquire()
Semaphore:acquire()
Wait for a permit from the semaphore. Your coroutine suspends until a slot opens up. If the owning task is cancelled, the acquire is cancelled too.
Returns: (maki.async.Permit) A permit handle. Call :release() when done, or let it be garbage collected.
Example:
local sem = maki.async.semaphore(3)
local permit = sem:acquire()
-- do work that needs the slot
permit:release()
Semaphore:try_acquire()
Semaphore:try_acquire()
Take a permit only if a slot is free right now, without waiting.
Returns: (maki.async.Permit|nil) A permit handle, or nil when every slot is taken.
Example:
local permit = sem:try_acquire()
if not permit then
print("waiting for a free slot")
permit = sem:acquire()
end
maki.async.Permit
One slot in a semaphore, obtained from Semaphore:acquire().
The slot is held until you call :release() or until the permit is
garbage collected. Releasing early lets other tasks acquire sooner.
Permit:release()
Permit:release()
Give the permit back to the semaphore so another task can acquire it. Throws if you already released this permit.
maki.async.Task
Handle returned by maki.async.spawn.
Task:cancel()
Task:cancel()
Stop the task. A task that is waiting ends right away and runs its
maki.async.on_cancel hooks. A task that cancels itself stops at its
next yield. Extra calls do nothing.
maki.base64
Base64 encoding and decoding, modelled after vim.base64.
Both functions accept strings and Luau buffers, so you can round-trip
binary data read with maki.fs.read_bytes.
local encoded = maki.base64.encode("hello")
local decoded = maki.base64.decode(encoded)
maki.base64.encode()
maki.base64.encode({data})
Encode {data} to standard Base64. Like vim.base64.encode.
Accepts both strings and Luau buffers.
Parameters:
{data}(string|buffer) Data to encode.
Returns: (string) Base64-encoded string.
Example:
maki.base64.encode("hello") -- "aGVsbG8="
maki.base64.decode()
maki.base64.decode({str})
Decode a Base64-encoded {str} back to its original bytes. Like vim.base64.decode.
Parameters:
{str}(string|buffer) Base64-encoded text.
Returns: (string?, string?) Decoded bytes as a string, or nil plus an error
message if {str} is not valid Base64.
Example:
maki.base64.decode("aGVsbG8=") -- "hello"
maki.env
Paths to maki's own directories (config, state, logs, legacy).
Use these to locate config files or persistent state without hard-coding paths.
These answer where maki keeps its files, so they need fs_read, which a
plugin needs to read anything there anyway. Asking for a path must not
cost a plugin env, which covers the process environment alone
(maki.uv.os_getenv), where secrets live.
local cfg = maki.env.config_dir()
maki.env.state_dir()
maki.env.state_dir()
Return the directory where maki stores runtime state (sessions, auth tokens, etc.).
Typically something like ~/.local/state/maki.
Requires the fs_read plugin permission.
Returns: (string?) State directory path, or nil if it cannot be determined.
Example:
local dir = maki.env.state_dir()
maki.env.config_dir()
maki.env.config_dir()
Return the directory where maki looks for user configuration files.
Typically something like ~/.config/maki.
Requires the fs_read plugin permission.
Returns: (string?) Config directory path, or nil if it cannot be determined.
Example:
local dir = maki.env.config_dir()
maki.env.logs_dir()
maki.env.logs_dir()
Return the directory where maki writes its log files (maki.log).
Typically something like ~/.local/logs/maki.
Requires the fs_read plugin permission.
Returns: (string?) Logs directory path, or nil if it cannot be determined.
Example:
local dir = maki.env.logs_dir()
maki.env.legacy_dir()
maki.env.legacy_dir()
Return the legacy config path (~/.maki), if it exists on disk.
Useful for migration logic. Returns nil when there is no legacy directory.
Requires the fs_read plugin permission.
Returns: (string?) Legacy directory path, or nil if not present.
maki.fn
Process and environment helpers, modeled after Neovim's vim.fn job
control. Use these to run shell commands, wait for output, and check
whether programs are installed.
local id = maki.fn.jobstart("git status", {
on_exit = function(_, code) print("done: " .. code) end,
})
maki.fn.jobstart()
maki.fn.jobstart({cmd}, {opts?})
Run a command in the background. A string runs through bash -c on Unix
and through agent.shell on Windows. A table
is spawned as argv with no shell, so nothing in it is read as a redirect, a
pipe, or $(...).
You get back a job id that you can pass to jobstop or jobwait to
control the process.
Output nobody has read yet waits in a queue of up to 16 MiB per job.
Past that the child blocks on write until on_stdout / on_stderr or
jobwait drain it, so a job started where nothing delivers its events,
like a tool handler before it returns, pauses there.
stdout and stderr route a stream to a file instead of into maki. A
path is opened for append and handed to the child, so nothing is buffered
here: no callback, no tail, no events for that stream, and it counts as
truncated everywhere a tail is reported. That makes the two mutually
exclusive with on_stdout / on_stderr for the same stream, and a path
additionally needs the fs_write permission. To both persist and react,
run one job writing the file and a second one tailing it.
Requires the run plugin permission.
Parameters:
{cmd}(string|table) Shell command, or an argv table like{ "tail", "-F", path }.{opts?}(table?) Optional settings:cwd(string?) working directory (tilde is expanded).env(table?) extra environment variables,{ VAR = "value" }.on_stdout(function?) called with(job_id, line, "stdout", bytes)for each stdout line, the stream name third as in Neovim (which passes a list of lines where maki passes one).bytesis the line's length beforemax_line_bytescut it, so it equals#lineunless the line was cut. Bytes that are not UTF-8 arrive as U+FFFD.on_stderr(function?) called with(job_id, line, "stderr", bytes)for each stderr line.on_exit(function?) called with(job_id, code)when the process finishes.stdout(string|false?) append stdout to this path, orfalseto discard it.stderr(string|false?) same for stderr; both may name one path.scope(string|table?) job lifetime."task"(default) ends the job with the current call."plugin"keeps it alive until the plugin unloads or reloads.{ session = "<id>" }keeps it alive until that session ends, and survives plugin reload.tail(integer?) trailing lines per stream kept forjobinfoandjobwait(default 20, 0 disables, max 1024).max_line_bytes(integer?) longest line delivered, in bytes. A longer line is cut at a UTF-8 boundary and ends in..., and its rest is skipped without being read into memory. Default,0, and max: 64 MiB.name(string?) handle forjobfind, unique among the live jobs this plugin can see. Starting a second job under a live name is an error.
Returns: (integer?, string?) Job id, or nil plus an error message when the
process could not start (binary not found, bad cwd, redirect file not
writable).
Example:
local id, err = maki.fn.jobstart({ "rg", "--json", pattern, dir }, {
on_stdout = function(_, line) print(line) end,
on_exit = function(_, code) print("exit: " .. code) end,
})
if not id then
maki.log.warn("rg failed to start: " .. err)
end
maki.fn.jobstop()
maki.fn.jobstop({job_id})
Kill a running job immediately (SIGKILL on Unix). Safe to call on jobs that already exited or on unknown ids.
Requires the run plugin permission.
Parameters:
{job_id}(integer) Job id returned byjobstart.
Example:
maki.fn.jobstop(id)
maki.fn.jobforget()
maki.fn.jobforget({job_id})
Drop an exited session-owned job from the store. Running jobs are left
alone; use jobstop to kill those. Unknown ids are a no-op.
Requires the run plugin permission.
Parameters:
{job_id}(integer) Job id returned byjobstart.
Example:
maki.fn.jobforget(id)
maki.fn.jobwait()
maki.fn.jobwait({job_id}, {timeout_ms?})
Wait for a job to finish and collect its output. Returns a result
table with stdout, stderr, exit_code, and truncated. The output
starts from the job's captured tail, which holds what was delivered before
the wait, and a live job adds every line from then on. truncated says
whether that tail had already lost a line by then (tail too small or 0,
or the stream redirected away). It doesn't count lines cut by
max_line_bytes: those still arrive, ending in ....
While waiting, the job's on_stdout, on_stderr, and on_exit
callbacks fire as events arrive (like Neovim), so you can stream
output into a buffer while parked here. An already-exited
session-owned job answers from its snapshot and fires no callbacks.
Task and plugin jobs leave the store on exit, so waiting after that
answers nil plus an error.
Requires the run plugin permission.
Parameters:
{job_id}(integer) Job id returned byjobstart.{timeout_ms?}(integer?) Maximum wait in milliseconds (default 30000).
Returns: (table?, string?) { stdout, stderr, exit_code, truncated }, or
nil plus an error on timeout or an unknown job.
Example:
local id = maki.fn.jobstart("echo hello")
local result, err = maki.fn.jobwait(id, 5000)
if result then
print(result.stdout)
end
maki.fn.jobinfo()
maki.fn.jobinfo({job_id})
Snapshot a job this plugin can see. Live jobs report tails collected so far; session-owned jobs still answer after they exit.
Requires the run plugin permission.
Parameters:
{job_id}(integer) Job id returned byjobstart.
Returns: (table|nil, string|nil) { id, command, name, pid, session, status, exit_code, elapsed_secs, stdout_lines, stderr_lines }, or nil and
an error. status is "running" or "exited".
Example:
local info = maki.fn.jobinfo(id)
maki.fn.joblist()
maki.fn.joblist({session?})
List jobs this plugin can see, including exited session-owned jobs (so an
id started before a reload stays findable). Rows identify the job; call
jobinfo for tails. Pass a session id to list only that session's jobs.
Plugin and task jobs carry no session, so a filter never matches them.
Requires the run plugin permission.
Parameters:
{session?}(string?) Session id filter.
Returns: (table) array of { id, command, name, pid, session, status, exit_code, elapsed_secs }.
Example:
local jobs = maki.fn.joblist(maki.session.current())
maki.fn.jobattach()
maki.fn.jobattach({job_id}, {opts})
Attach (or replace) callbacks on a job this plugin can see. This is how a plugin picks its jobs back up after a reload: unloading drops the Lua callbacks of its session-owned jobs, but the processes keep running.
Keys absent from {opts} leave the current callback alone. Attaching
on_exit to a job that already exited still fires it once, with the
recorded exit code, so a reload racing the exit cannot lose it.
Requires the run plugin permission.
Parameters:
{job_id}(integer) Job id, e.g. fromjoblist.{opts}(table)on_stdout,on_stderr,on_exit: a function, orfalseto clear.
Returns: (boolean|nil, string|nil) true on success, or nil and an error.
Example:
-- A monitor that survives /reload: adopt the live job or start one.
local sid = maki.session.current()
local id = maki.fn.jobfind("log-tail")
or maki.fn.jobstart({ "tail", "-F", path }, {
name = "log-tail",
scope = { session = sid },
})
maki.fn.jobattach(id, {
on_stdout = function(_, line) maki.session.notify(line, { session = sid }) end,
on_exit = function(_, code) maki.session.notify("tail died: " .. code, { session = sid }) end,
})
maki.fn.jobfind()
maki.fn.jobfind({name})
Find the live job of this plugin that jobstart registered under {name}.
An exited job never answers, so jobfind(...) or jobstart(...) restarts a
job that died instead of adopting its id. The name stays on the joblist
row, which is where you go to see why it died.
Requires the run plugin permission.
Parameters:
{name}(string) Name passed tojobstart.
Returns: (integer|nil, string|nil) Job id, or nil and an error when no live
job holds the name.
Example:
local id = maki.fn.jobfind("log-tail")
if not id then
id = maki.fn.jobstart("tail -F /tmp/log", { name = "log-tail", scope = "plugin" })
end
maki.fn.executable()
maki.fn.executable({name})
Check whether {name} can be found on $PATH or is an absolute path
to a file. Returns 1 when found, 0 otherwise (matches Neovim's
vim.fn.executable).
Requires the fs_read plugin permission.
Parameters:
{name}(string) Program name (e.g."git") or absolute path.
Returns: (integer) 1 if found, 0 otherwise.
Example:
if maki.fn.executable("rg") == 1 then
-- use ripgrep
end
maki.fn.winsaveview()
maki.fn.winsaveview()
Read the viewport of the focused chat transcript, like Neovim's
vim.fn.winsaveview(). The transcript is the only scrollable window
maki has, so there is no window argument.
topline is the 1-based transcript line at the top of the viewport, so
the last visible one is math.min(topline + height - 1, line_count).
auto_scroll has no Vim counterpart: it is true while the transcript
follows streaming output.
Returns: (table|nil, string|nil) {topline, line_count, height, auto_scroll}, or nil and an error.
Example:
local view = maki.fn.winsaveview()
maki.fn.winrestview({ topline = view.topline + 1 })
maki.fn.winrestview()
maki.fn.winrestview({view})
Scroll the focused chat transcript so that the topline field of
{view} becomes the top visible line, like Neovim's
vim.fn.winrestview(). Out of range values are clamped. Other keys are
ignored, so a table straight from winsaveview() round-trips.
Scrolling away from the bottom unpins the transcript; landing back at the bottom re-pins it so streaming output keeps following.
Parameters:
{view}(table) View to restore. Onlytopline(1-based) is read.
Returns: (boolean|nil, string|nil) true on success, or nil and an error.
Example:
maki.fn.winrestview({ topline = 1 })
maki.fn.mode()
maki.fn.mode()
The current mode, like vim.fn.mode(): "i" while the chat input has
the keyboard and takes typed text, "n" otherwise. See
Modes. Always "n" without a UI.
Returns: (string) "n" or "i".
Example:
maki.keymap.set({ "n", "i" }, "<M-m>", function()
maki.ui.set_mode(maki.fn.mode() == "n" and "i" or "n")
end)
maki.fs
File-system utilities, modelled after vim.fs and vim.uv.
Fallible operations return (value, err) pairs and never throw.
Paths support ~/ expansion. Relative paths resolve from the current working directory.
local text, err = maki.fs.read("init.lua")
if err then return end
maki.fs.read()
maki.fs.read({path}, {opts?})
Read the file at {path} as a UTF-8 string. Pass {opts} to read only some
lines, such as the end of a log.
Returns nil plus an error message if the text read is over 64 MiB or not
valid UTF-8. Skipped lines do not count, so tailing a huge log works.
Use read_bytes for binary files.
Requires the fs_read plugin permission.
Parameters:
{path}(string) Absolute or relative file path.~/is expanded to the home directory.{opts?}(table?)offsetis the 1-based line to start at (default 1). A negative value counts back from the end, so-50reads the last 50 lines. An offset past the end returns an empty string.limitis the max number of lines,0or omitted reads to the end.
Returns: (string?, string?) File contents, or nil plus an error message.
Example:
local text, err = maki.fs.read("config.toml")
if err then
maki.log.warn("could not read config: " .. err)
return
end
local tail = maki.fs.read("server.log", { offset = -50 })
maki.fs.read_bytes()
maki.fs.read_bytes({path}, {opts?})
Read the file at {path} as raw bytes in a Luau buffer. Pass {opts} to read
a byte range.
Returns nil plus an error message if the bytes read are over 64 MiB.
Use it for binary files or data headed for maki.base64.encode.
Requires the fs_read plugin permission.
Parameters:
{path}(string) Absolute or relative file path.~/is expanded to the home directory.{opts?}(table?)offsetis the byte to start at (default 0). A negative value counts back from the end, so-1024reads the last 1024 bytes.lenis the max number of bytes, omitted reads to the end.
Returns: (buffer?, string?) File bytes as a Luau buffer, or nil plus an error message.
Example:
local buf, err = maki.fs.read_bytes("image.png")
if err then return end
local encoded = maki.base64.encode(buf)
local header = maki.fs.read_bytes("image.png", { len = 8 })
maki.fs.read_lines()
maki.fs.read_lines({path}, {opts?})
Read a page of lines from the file at {path}, holding only that page, and
count every line of the file in the same pass. With max_line_bytes, a
file of any size pages fine, even one that is a single huge line.
Lines come without their \n or \r\n, and a trailing newline does not
start a new line: a\nb\n has 2 lines.
Returns nil plus an error message if the page is over 64 MiB or not valid
UTF-8.
Requires the fs_read plugin permission.
Parameters:
{path}(string) Absolute or relative file path.~/is expanded to the home directory.{opts?}(table?)offsetis the 1-based line to start at (default 1).limitis the max number of lines,0or omitted reads to the end.max_line_bytescuts longer lines (at most 64 MiB) at a UTF-8 boundary and appends..., omitted or0keeps lines whole.count = falsestops reading after the page and leavestotalnil.
Returns: (table?, string?) { lines = string[], total = integer? }, or nil plus an error message.
Example:
local page, err = maki.fs.read_lines("server.log", { offset = 101, limit = 100, max_line_bytes = 500 })
if err then return end
print(("lines 101-%d of %d"):format(100 + #page.lines, page.total))
maki.fs.metadata()
maki.fs.metadata({path})
Get metadata for the file or directory at {path}.
Returns a table with size (integer), is_file (boolean), is_dir (boolean),
and mtime (number, fractional seconds since the Unix epoch; absent when the
filesystem does not report a modification time).
If {path} does not exist, returns nil with no error.
Requires the fs_read plugin permission.
Parameters:
{path}(string) Absolute or relative path.
Returns: (table?, string?) Metadata table, nil if missing, or nil plus an error message.
Example:
local meta = maki.fs.metadata("src/main.rs")
if meta and meta.is_file then
print("size: " .. meta.size)
end
maki.fs.dirname()
maki.fs.dirname({path})
Return the parent directory of {path}. Like vim.fs.dirname.
Parameters:
{path}(string) File path.
Returns: (string?) Parent directory, or nil if {path} has no parent.
Example:
maki.fs.dirname("/home/user/init.lua") -- "/home/user"
maki.fs.basename()
maki.fs.basename({path})
Return the final component (the file name) of {path}. Like vim.fs.basename.
Parameters:
{path}(string) File path.
Returns: (string?) File name, or nil for paths like /.
Example:
maki.fs.basename("/home/user/init.lua") -- "init.lua"
maki.fs.joinpath()
maki.fs.joinpath({...})
Join one or more path segments into a single path. Like vim.fs.joinpath.
Parameters:
{...}(string) One or more path segments to join.
Returns: (string) The joined path.
Example:
maki.fs.joinpath("src", "api", "fs.rs") -- "src/api/fs.rs"
maki.fs.normalize()
maki.fs.normalize({path})
Clean up . and .. segments and make {path} absolute. Like vim.fs.normalize.
This is purely string-based and does not touch the filesystem.
Parameters:
{path}(string) Path to normalize.~/is expanded.
Returns: (string) Normalized absolute path.
Example:
maki.fs.normalize("src/../src/api") -- "/home/user/project/src/api"
maki.fs.abspath()
maki.fs.abspath({path})
Make {path} absolute by prepending the current working directory when needed.
Unlike normalize, this does not resolve . or .. segments.
Parameters:
{path}(string) Relative or absolute path.~/is expanded.
Returns: (string) Absolute path.
Example:
maki.fs.abspath("src/main.rs") -- "/home/user/project/src/main.rs"
maki.fs.parents()
maki.fs.parents({path})
Return all ancestor directories of {path}, from the immediate parent up to the root. Handy for walking up a directory tree.
Parameters:
{path}(string) File or directory path.
Returns: (string[]) Array of ancestor directory paths.
Example:
local dirs = maki.fs.parents("/home/user/project/src")
-- { "/home/user/project", "/home/user", "/home", "/" }
maki.fs.root()
maki.fs.root({source}, {marker})
Walk upward from {source} looking for a directory that contains one of the
{marker} files or directories. Like vim.fs.root. Useful for finding the
project root.
Requires the fs_read plugin permission.
Parameters:
{source}(string) Starting file or directory path.{marker}(string|string[]) Marker filename(s) to look for, e.g.".git"or{"package.json", ".git"}.
Returns: (string?, string?) Root directory path, or nil when not found.
Example:
local root = maki.fs.root("src/main.rs", { ".git", "Cargo.toml" })
if root then print("project root: " .. root) end
maki.fs.relpath()
maki.fs.relpath({base}, {target})
Compute a relative path from {base} to {target}.
Parameters:
{base}(string) Base directory path.{target}(string) Target path.
Returns: (string) Relative path from {base} to {target}.
Example:
maki.fs.relpath("/home/user", "/home/user/project/src") -- "project/src"
maki.fs.ext()
maki.fs.ext({path})
Return the file extension of {path}, without the leading dot.
Parameters:
{path}(string) File path.
Returns: (string?) Extension, or nil if the path has no extension.
Example:
maki.fs.ext("main.rs") -- "rs"
maki.fs.ext("Makefile") -- nil
maki.fs.dir()
maki.fs.dir({path}, {opts?})
List the contents of the directory at {path}.
Each entry is a two-element array {name, type} where type is one of
"file", "directory", "link", or "unknown". Follows symlinks.
name is relative to {path}, so nested entries (depth > 1) keep their
directory, as in "tests/lib.rs".
Requires the fs_read plugin permission.
Parameters:
{path}(string) Directory path.{opts?}(table?)depth(integer, default 1): how many levels deep to recurse.
Returns: (table?, string?) Array of {name, type} entries, or nil plus an error message.
Example:
local entries, err = maki.fs.dir("src", { depth = 2 })
if err then return end
for _, e in ipairs(entries) do
print(e[1], e[2]) -- "main.rs" "file", "tests/lib.rs" "file"
end
maki.fs.write()
maki.fs.write({path}, {content})
Write {content} to the file at {path}, creating it if it does not exist or overwriting it if it does.
Requires the fs_write plugin permission.
Parameters:
{path}(string) Destination file path.~/is expanded.{content}(string|buffer) Bytes to write.
Returns: (true?, string?) true on success, or nil plus an error message.
Example:
local ok, err = maki.fs.write("out.txt", "hello world")
if err then print("write failed: " .. err) end
maki.fs.append()
maki.fs.append({path}, {content})
Append {content} to the file at {path}, creating it (but not its parent directory) if it does not exist.
Requires the fs_write plugin permission.
Parameters:
{path}(string) Destination file path.~/is expanded.{content}(string|buffer) Bytes to append.
Returns: (true?, string?) true on success, or nil plus an error message.
Example:
local ok, err = maki.fs.append("out.log", "line\n")
if err then print("append failed: " .. err) end
maki.fs.atomic_write()
maki.fs.atomic_write({path}, {content})
Atomically replace {path} with {content}. The parent directory must exist. Readers observe either the old file or the complete new file. Existing file permissions are preserved. On Unix, new files use mode 0600.
Requires the fs_write plugin permission.
Parameters:
{path}(string) Destination file path.~/is expanded.{content}(string|buffer) Bytes to write.
Returns: (true?, string?) true on success, or nil plus an error message.
Example:
local ok, err = maki.fs.atomic_write("state.json", encoded)
if err then print("atomic write failed: " .. err) end
maki.fs.rename()
maki.fs.rename({from}, {to})
Move the file or directory at {from} to {to}, replacing {to} if it is an existing file. Both must be on the same filesystem. Nothing is copied, so renaming a large file costs the same as a small one.
Requires the fs_write plugin permission.
Parameters:
{from}(string) Path to move.{to}(string) New path.~/is expanded.
Returns: (true?, string?) true on success, or nil plus an error message.
Example:
local ok, err = maki.fs.rename("out.log", "out.log.1")
if err then print("rename failed: " .. err) end
maki.fs.rm()
maki.fs.rm({path}, {opts?})
Delete the file, symlink, or directory at {path}.
Pass recursive = true to remove a non-empty directory tree (like rm -r).
Unlike vim.fs.rm, this also removes an empty directory without recursive.
Symlinks are removed themselves, never followed.
Requires the fs_write plugin permission.
Parameters:
{path}(string) Path to the file or directory to remove.{opts?}(table?)recursive(boolean, default false): remove a directory and its contents recursively.force(boolean, default false): silently ignore a missing path.
Returns: (true?, string?) true on success, or nil plus an error message.
Example:
local ok, err = maki.fs.rm("temp.txt")
if err then print("rm failed: " .. err) end
maki.fs.rm("stale_dir", { recursive = true, force = true })
maki.fs.mkdir()
maki.fs.mkdir({path}, {opts?})
Create the directory at {path}. Set parents = true to create
intermediate directories, like mkdir -p.
Requires the fs_write plugin permission.
Parameters:
{path}(string) Directory path to create.{opts?}(table?)parents(boolean, default false): create intermediate parent directories.
Returns: (true?, string?) true on success, or nil plus an error message.
Example:
maki.fs.mkdir("a/b/c", { parents = true })
maki.fs.glob()
maki.fs.glob({pattern}, {opts?})
Find files matching one or more glob patterns, walked fresh on every call.
Reads any path the plugin is allowed to read and keeps nothing afterwards.
maki.fs.fuzzy_files ranks a walk the host caches instead, which is
cheaper per keystroke but only covers the current working directory.
Respects .gitignore by default. Pass sort = "mtime" to get the most
recently modified files first.
Requires the fs_read plugin permission.
Parameters:
{pattern}(string|string[]) Glob pattern or array of patterns.{opts?}(table?)path(string): search root.limit(integer): max results.gitignore(boolean, default true): respect .gitignore.sort(string):"mtime"sorts newest first.
Returns: (string[]?, string?) Array of absolute file paths, or nil plus an error message.
Example:
local files, err = maki.fs.glob("**/*.lua", { path = "plugins", limit = 10 })
if err then return end
for _, f in ipairs(files) do print(f) end
maki.fs.grep()
maki.fs.grep({pattern}, {opts?})
Search file contents for a regex {pattern}. Returns structured matches grouped by file, similar to ripgrep output.
Each result entry has a path and a list of groups. Each group contains
lines, where every line has line_nr, text, and is_match.
Requires the fs_read plugin permission.
Parameters:
{pattern}(string) Regular expression to search for.{opts?}(table?)path(string): search root.include(string): file glob filter (e.g."*.rs").context_before/context_after(integer): context lines around matches.limit(integer): max match groups.max_line_bytes(integer): truncate lines longer than this (0 means unlimited).
Returns: (table?, string?) Array of {path, groups} tables, or nil plus an error message.
Example:
local hits, err = maki.fs.grep("TODO", { path = "src", include = "*.rs", limit = 5 })
if err then return end
for _, file in ipairs(hits) do
for _, g in ipairs(file.groups) do
for _, line in ipairs(g.lines) do
if line.is_match then print(file.path .. ":" .. line.line_nr) end
end
end
end
maki.fs.fuzzy_files()
maki.fs.fuzzy_files({opts?})
Rank the files and directories under {opts.path} against {opts.query} and return the best ones, best first, with the state of the walk behind them.
The host walks each root once and shares that walk with the built-in file
picker (Ctrl+S), so a call ranks an existing list instead of walking the
tree, and both rank alike. Use maki.fs.glob for patterns, a path outside
the cwd, or a tree read fresh right now. Only limit items ever cross into
Lua whatever the size of the repo, paths come back relative to the root
with a trailing separator on the directories, and .gitignore and .git
are respected. highlights cost a second matcher pass, so ask for them
only to draw matches.
complete is false while a walk is filling the list, so an empty items
means "not found yet" and asking again is worth it. maki walks a bounded
number of trees at once, so a first call can also answer before the walk it
asked for has started. crashed and truncated are the two ways a
complete list is still not the whole tree: a walker that died partway
through it, and a tree bigger than the host's ceiling. Listen for
"FileIndexReady" with maki.api.create_autocmd to be told when a walk
lands rather than polling for it.
The tools that write, move and delete files mark the tree they touched, so
a call a moment after an edit re-walks and a file the agent just wrote is
findable. A file a bash command creates or deletes is not: a shell
command cannot say what it touched, and maki does not try to guess. That
leaves the staleness window as the only guarantee, and it is this: a walk
is redone the first time anything asks for the index more than twenty
seconds after the last one landed, so a path may be missing from the list,
or offered after it is gone, for up to twenty seconds.
A second call from the same plugin cancels the one in flight, which answers with nil plus an error. While the user types that is expected, so treat the error as a stale answer. A plugin reading more than four roots keeps the four it asked for most recently: the walk behind an older one is let go and asking for it again walks it again.
Requires the fs_read plugin permission.
Parameters:
{opts?}(table?) Options:query(string) what the user typed. Empty returns the firstlimitpaths in walk order.limit(integer) how many items to return, at most 500. Default 20.path(string) the root to search, the cwd or below it. Default is the current working directory.highlights(boolean) also return where the query matched each path. Default false.
Returns: (table?, string?) { root = string, complete = boolean, crashed = boolean, truncated = boolean, items = { { path = string, highlights = integer[][]? } } }, or nil plus an error message. root is the resolved absolute directory the paths are relative to, spelled the way "FileIndexReady" spells it, so an event can be matched to the call that caused it. It is absent for a directory with no UTF-8 spelling, as it is on the event, so a plugin that gets no root treats every event as a reason to ask again rather than matching the wrong tree. items is a 1-based array, best first. highlights is only present when asked for, and holds { from, to } byte ranges of path, ascending, 1-based and inclusive, so path:sub(from, to) is the matched text.
Example:
local res, err = maki.fs.fuzzy_files({ query = "src/mai", limit = 20, highlights = true })
if err then return end -- a newer call took over, this answer is stale
for _, item in ipairs(res.items) do
local r = item.highlights[1]
print(item.path, r and item.path:sub(r[1], r[2]))
end
if not res.complete then print("still scanning, ask again") end
maki.image
Small building blocks for working with images: probe metadata, decode pixels, resize, and encode back to bytes. Plugins compose these freely.
Decoding is guarded against pixel-bomb attacks (50 MP limit).
local img = maki.image.decode(raw_bytes)
local small = img:resize(1024, 768)
local png = small:encode("png")
maki.image.probe()
maki.image.probe({data})
Read image metadata (format, dimensions) from raw bytes without fully
decoding the pixels. Much faster than decode when you only need to
check the size or format.
Returns a table with format (string), width (integer), height
(integer), or (nil, err) if the bytes are not a recognized image.
Parameters:
{data}(string|buffer) Raw image bytes.
Returns: (table?, string?) Info table, or (nil, err) on failure.
Example:
local info, err = maki.image.probe(raw_bytes)
if err then error(err) end
print(info.format, info.width, info.height)
maki.image.decode()
maki.image.decode({data})
Decode raw image bytes into an Image handle you can resize and re-encode. The whole image is decoded up front, so corrupt input fails here rather than later. Images larger than 50 megapixels are rejected to prevent memory bombs. Formats other than png, jpeg, gif, and webp (like bmp) are converted to png, so the image can go into a message.
Parameters:
{data}(string|buffer) Raw image bytes.
Returns: (maki.image.Image?, string?) Decoded image, or (nil, err) on failure.
Example:
local img, err = maki.image.decode(raw_bytes)
if err then error(err) end
print(img:width() .. "x" .. img:height())
maki.image.Image
An image you can inspect, resize, and re-encode.
Get one from maki.image.decode(). It always holds encoded bytes as
png, jpeg, gif, or webp, and decodes the pixels on first use. As a
message image source or through maki.json.encode it becomes
{ type = "base64", media_type, data }. The data lives in memory
until the handle is garbage collected.
Image:width()
Image:width()
Get the width of the image in pixels. Reads only the header when the pixels are not decoded yet.
Returns: (integer) Width in pixels.
Image:height()
Image:height()
Get the height of the image in pixels. Reads only the header when the pixels are not decoded yet.
Returns: (integer) Height in pixels.
Image:resize()
Image:resize({max_w}, {max_h})
Shrink the image to fit inside {max_w} x {max_h}, keeping the aspect
ratio. If the image already fits, it is returned as-is. Never upscales.
A resized image is JPEG if the source was JPEG and PNG otherwise, which
decides its media_type when placed into a message.
Parameters:
{max_w}(integer) Maximum width in pixels. Must be positive.{max_h}(integer) Maximum height in pixels. Must be positive.
Returns: (maki.image.Image) A new image handle (or the same one if no resize was needed).
Example:
local img = maki.image.decode(raw_bytes)
local small = img:resize(800, 600)
local encoded = small:encode("jpeg")
Image:encode()
Image:encode({format})
Encode the image into raw bytes in the given format. Use this to prepare
images for sending over the network or writing to disk. Bytes that came
from outside are always re-encoded, so this can shrink an oversized file.
An image from resize asked for its own format comes back as is.
Parameters:
{format}(string) Output format:"png","jpeg", or"jpg".
Returns: (string) Encoded image bytes.
Example:
local bytes = img:encode("png")
-- bytes is a Lua string containing the raw PNG data
maki.interpreter
Run Python code in a memory-safe, time-limited sandbox.
The sandbox uses the monty interpreter. Python code can call back into Lua-defined tools, and stdout is streamed line by line.
local r, err = maki.interpreter.run("print('hello')", {
timeout = 10,
max_memory_mb = 128,
on_output = function(line) print(line) end,
})
maki.interpreter.run()
maki.interpreter.run({code}, {opts})
Run Python code in a sandboxed interpreter with memory and time limits. Stdout lines are streamed to your {on_output} callback as they are produced. If the Python code calls tools, those calls are dispatched to the Lua functions you provide in {opts}.tools.
The result table has optional fields: stdout (string, trimmed combined
output) and output (string, the final expression value). On error, the
table is empty and the second return value is the error message.
Requires the run plugin permission.
Parameters:
-
{code}(string) Python source code to execute. -
{opts}(table) Required fields:timeout(integer) execution time limit in seconds.max_memory_mb(integer) memory limit in megabytes.on_output(function) called with each stdout line (string) as it is produced. Must not yield.
Optional fields:
preamble(string?) Python source (imports, helpers) compiled ahead of {code}. Tracebacks are rebased so line 1 is {code} line 1.tools(table?) map ofname -> functionfor tools the sandbox may call. Each function receives the tool input table and must return(string)or(nil, err). Tool calls are batched and dispatched concurrently.files(table?) callbacks that serveopen(),osandpathlib. Without it, any OS call ends the run. A missing callback refuses that access, and(nil, err)refuses one call. Binary I/O, removing and renaming always raiseRuntimeError.os.getenvsees only non-secret variables likeHOME. Sleeps and metadata queries,inspectincluded, share a budget oftimeoutseconds, and going over ends the run.read(path)returns(content). A refusal raisesOSError.write(path, content, append)returns(string)or(true). Writes are buffered per file, and flushed before a read of that file, before any tool call or metadata query, and at the end of the run. A cancelled run drops them. A failed flush ends the run, unless a read triggered it, then the read raisesOSError.inspect(path)gets the absolute path of each metadata query (os.stat,os.walk,Path.glob) and returns(true)to allow it. A walk or glob covers everything under {path}. A refusal raisesRuntimeError. Needs thefs_readpermission.mkdir(path, parents)returns(true)once the directory exists. It only gets missing paths that passedinspect. A refusal raisesOSError.
Returns: (table, string?) Result table, plus an error string on failure.
Example:
local result, err = maki.interpreter.run("print(2 + 2)", {
timeout = 30,
max_memory_mb = 256,
on_output = function(line) print("py: " .. line) end,
})
if err then error(err) end
if result.stdout then print(result.stdout) end
maki.json
JSON encoding, decoding, and schema validation. Encode Lua tables to JSON strings, decode JSON back into tables, and optionally validate data against a JSON Schema.
local s = maki.json.encode({ ok = true })
local t = maki.json.decode(s)
maki.json.encode()
maki.json.encode({value})
Turn a Lua value into a JSON string. Tables, strings, numbers,
booleans, nil, and maki.NIL (which becomes null) all work. A
maki.image.Image becomes { type = "base64", media_type, data }.
Functions, threads, other userdata, and tables that contain themselves
cannot be encoded.
A table is an array when it came from a JSON array (maki.json.decode,
maki.deepcopy of one), or when all its keys are positive integers and
its largest key is at most 10 or at most twice the number of keys, with
null in the gaps like vim.json.encode. Any other table is an object,
with number and boolean keys written as strings.
Parameters:
{value}(any) Lua value to encode.
Returns: (string?, string?) JSON string, or nil plus an error.
Example:
local s, err = maki.json.encode({ name = "maki", version = 1 })
print(s) -- {"name":"maki","version":1}
maki.json.decode()
maki.json.decode({str}, {opts?})
Parse a JSON string into a Lua value. Objects become tables and
arrays become 1-indexed sequences. Every JSON null becomes maki.NIL, so
a key holding null is still there and encoding the result gives the same
JSON back. maki.NIL is a special value that stands for JSON null. It is
truthy, so test for null with x == maki.NIL.
Pass opts.luanil to get plain nil instead, like vim.json.decode.
luanil.object does so for nulls inside objects and luanil.array for
nulls inside arrays. A null at the top level is always maki.NIL.
Parameters:
{str}(string) JSON string to decode.{opts?}(table?) Optional.luanil(table with booleanobjectandarray) turns those nulls into nil.
Returns: (any?, string?) Decoded value, or nil plus an error.
Example:
local t, err = maki.json.decode('{"x": 42, "y": null}')
print(t.x) -- 42
print(t.y == maki.NIL) -- true
local u = maki.json.decode('{"y": null}', { luanil = { object = true } })
print(u.y) -- nil
maki.json.schema_validator()
maki.json.schema_validator({schema})
Compile a JSON Schema into a reusable validator object. Supports draft-07, 2019-09, and 2020-12. Schema errors show up right away so you catch mistakes before doing any real work.
Parameters:
{schema}(table) JSON Schema as a Lua table.
Returns: (maki.json.SchemaValidator?, string?) Validator, or nil plus an error.
Example:
local v, err = maki.json.schema_validator({
type = "object",
properties = { name = { type = "string" } },
required = { "name" },
})
local errs = v:validate({ name = "maki" })
assert(errs == nil)
maki.json.SchemaValidator
A compiled JSON Schema validator. Create one with maki.json.schema_validator() and reuse it to validate many values without recompiling the schema each time.
SchemaValidator:validate()
SchemaValidator:validate({value})
Check {value} against the compiled schema. Returns nil when the value is valid. When validation fails, returns a list of human-readable error strings.
Parameters:
{value}(any) The Lua value to validate.
Returns: (table?) Array of error strings, or nil if valid.
Example:
local errs = validator:validate({ name = 123 })
if errs then
for _, msg in ipairs(errs) do print(msg) end
end
maki.keymap
Key mappings, modeled after vim.keymap.
maki.keymap.set({ "n", "i" }, "<C-t>", function()
print("hello")
end, { desc = "Say hello" })
Modes
As in Neovim, maki is in one mode at a time, and a binding fires only in the modes it was set for.
| Mode | When |
|---|---|
"i" (insert, the default) | The chat input has the keyboard, and keys type into it. |
"n" (normal) | Set by maki.ui.set_mode("n"), and while a picker, modal, prompt or focused window has the keyboard or a finished subagent's chat is shown. |
The mode a plugin set comes back when the chat input gets the keyboard
again. In normal mode, keys never type or delete in the chat input.
Moving the cursor, history, pasting and <CR> to send still work.
Bind a shortcut in { "n", "i" } to make it work everywhere, as the
built-in plugins do. Read the mode with maki.fn.mode(), and watch it
with the "ModeChanged" autocmd.
-- A tiny vim mode: Esc leaves insert mode, i goes back.
maki.keymap.set("i", "<Esc>", function() maki.ui.set_mode("n") end)
maki.keymap.set("n", "i", function() maki.ui.set_mode("i") end)
-- dd deletes the cursor's line. A lone d expires after 500 ms.
local pending
maki.keymap.set("n", "d", function(ev)
if not pending then
pending = maki.defer_fn(function() pending = nil end, 500)
return
end
pending:stop()
pending = nil
local st = ev.input
local head = st.text:sub(1, st.cursor):match("^.*\n")
maki.ui.input_edit({
start = head and #head or 0,
stop = st.text:find("\n", st.cursor + 1, true) or #st.text,
text = "", version = st.version, session_id = st.session_id,
})
end)
With this <Esc> binding, the built-in Esc Esc (rewind) works only
from normal mode.
Older versions fired "n" bindings while you typed. See
Upgrading old keymaps.
Key resolution
Each key runs one handler: the first match in this list, for the current mode.
<C-c>and<C-z>, which no binding can take.<C-z>suspends here, and<C-c>still goes to step 2 first.- Maki's modals and prompts, then the focused window, then Maki's
pickers. They take every key, except the plan form and the
/command list, which pass on the keys they do not use. The focused window runs its buffer's bindings, then itswin:recv. - Windows on screen, front first: each one's buffer bindings, then
the keys it claimed with the
keysoption ofmaki.ui.open_win. <Esc>while the agent runs, in either mode. Maki takes it, and a second one in a row cancels the turn.- Global bindings, the last
setfirst. - Maki's built-in keys and the chat input.
ev.fallback() jumps to step 6, or to win:recv for a binding on the
focused window's buffer. <Paste> follows the same list.
To share one key between plugins, see Composing keys.
Key notation
set, del, the keys option of maki.ui.open_win and win:recv
key events all use one notation. normalize converts any accepted
spelling to the canonical one.
if ev.type == "key" and ev.key == "<CR>" then submit() end
A single character stands for itself: a, A, 7, ?. Other keys
go in angle brackets, after any modifiers.
| Key | Notation | Also accepted |
|---|---|---|
| Enter | <CR> | <Enter>, <Return> |
| Escape | <Esc> | <Escape> |
| Backspace | <BS> | <Backspace> |
| Delete | <Del> | <Delete> |
| Tab | <Tab> | |
| Shift+Tab | <S-Tab> | |
| Space | <Space> | |
| Arrows | <Up>, <Down>, <Left>, <Right> | |
| Navigation | <Home>, <End>, <PageUp>, <PageDown>, <Insert> | |
| Function keys | <F1> through <F24> | |
| Bracketed paste | <Paste> |
Modifiers are C- (control), M- (alt) and S- (shift), in that
order: <C-M-x>. Ctrl-, Alt-, A- and Shift- are accepted as
input.
Terminals report some keys differently, so maki picks one form:
- Control plus a letter is lowercase:
<C-N>is<C-n>, as in Vim. - Shift plus a letter is the uppercase letter:
<S-a>isA. - Without control or alt, shift is part of the char typed, so the key
is that char: Shift+1 on a US layout is
!, and<S-!>is!.<S-Space>is<Space>. With alt the prefix stays:<M-S-1>. - Shift+Tab is always
<S-Tab>, with or without the kitty keyboard protocol.
Key strings in a plugin and every module it requires are checked at
load. Each invalid one is logged with its file and line, and the status
bar shows a summary, so a typo shows up at startup.
Upgrading from older versions: win:recv used to deliver "enter",
"esc", "ctrl+n" and "shift+tab". These now arrive as <CR>,
<Esc>, <C-n> and <S-Tab>, and the load check flags the old
spellings.
maki.keymap.set()
maki.keymap.set({mode}, {lhs}, {rhs}, {opts?})
Bind a key to a Lua function, like vim.keymap.set.
The binding fires only in the modes you list. A
key bound in "i" no longer types, so bind keys like <Tab> or <C-x>
there, rarely a letter. A binding on a key that types text, like a,
<Space> or <Paste>, needs session_read in every mode, because it
sees what the user types. A plugin may switch the mode itself, so a
letter bound in "n" could hear every key the user meant to type. That
goes for a buffer binding too, since its window can sit on screen while
the user types into the chat input. Keys
with C- or M-, function keys and keys like <CR>, <Esc>, <Tab>,
<BS> or the arrows need nothing.
Key resolution shows which binding gets
a key.
Bindings belong to the plugin that set them and stack per mode. The last
set wins and logs a warning naming the plugin it shadows. When that
plugin calls del or unloads, the shadowed binding comes back. Setting a
key you already hold replaces your binding.
A binding with opts.buffer comes before any global binding and goes
away with the buffer. Use it for the keys of a popup. A handler that
refers to the buffer keeps it alive, so del it when the popup closes.
The handler consumes the key, even when it throws (the error is logged).
Call ev.fallback() to let maki handle the key after all. A handler that
changes the text of the input needs input, agent and session_write,
see chat input.
While a handler runs, the keys, pastes and clicks after it wait, so its edits and mode switches are in place before the next key lands. Keys wait one second at most, and stop waiting when another window takes the keyboard, like a picker the handler opened. If a modal or a prompt opens meanwhile, like an alert, a permission prompt or a question, the waiting keys are dropped so they cannot answer it, and the status bar says so.
Every key waits its turn, also <Esc> while the agent runs, except
<C-c> and <C-z>. A <C-c> drops the pending ev.fallback(). If keys
were waiting, it drops them too and the status bar says so, and only the
next <C-c> works as usual. Otherwise it works as usual right away.
A key never sends text that changed after it was pressed, because the
user never saw what it would send. If the input changed or the keyboard
moved while a <CR> waited, maki drops that send and asks the user to
press Enter again. The same goes for ev.fallback() on <CR> after any
change since the press, your handler's own edits included. To send what
your handler wrote, use
maki.ui.input_submit.
Throws on an invalid mode or key, on <C-c> and <C-z>, which stay
reserved for quit and suspend, on a taken key with unique, and with
permission denied on a typing key in "i" without session_read.
Parameters:
{mode}(string|string[])"n","i", or a list of them.{lhs}(string) Key in Vim notation, e.g."<C-t>","a", or"<Paste>"for bracketed paste.{rhs}(function) Called with an event tableev. The return value is ignored.evhas:key(string) the key, in canonical notation.input(table?) the chat input at the press, asmaki.ui.inputreturns it. Pass itsversionandsession_idtomaki.ui.input_edit. Only withsession_read, else nil.text(string?)<Paste>only: the pasted text, with\nline endings. maki does not insert it. It is cleaned the waymaki.ui.input_editcleans text, so#ev.textis what inserting it adds. Only withsession_read, else nil.fallback(function) runs maki's own handling of the key, as if no plugin had bound it (see Key resolution). Call it once, before the handler returns.- It lands after the handler's earlier
maki.uicalls and before the waiting keys. - It returns
trueonce the key is queued, orniland an error. - The key is dropped if the keyboard, the mode, the cursor or the selection moved since the press, your handler's own changes included.
- It lands after the handler's earlier
{opts?}(table?) Options:desc(string) shown next to the key in/help.unique(boolean) throw, naming the owner, when the key is already bound in one of the modes. Default false.buffer(Buf) bind the key only while a window showing this buffer is on screen.
Example:
-- Tab in an empty input starts a review prompt, else it switches plan/build:
maki.keymap.set("i", "<Tab>", function(ev)
local st = ev.input
if st.text ~= "" then
return ev.fallback()
end
maki.ui.input_edit({
start = 0, stop = 0, text = "Review the staged changes: ",
version = st.version, session_id = st.session_id,
})
end)
-- Keys of a popup, live only while it is on screen:
local buf = maki.ui.buf()
local win = maki.ui.open_win(buf, { focus = false, width = 20, height = 3 })
maki.keymap.set("i", "<Esc>", function()
maki.keymap.del("i", "<Esc>", { buffer = buf })
win:close()
end, { buffer = buf })
maki.keymap.del()
maki.keymap.del({mode}, {lhs}, {opts?})
Remove your plugin's binding for {lhs} in {mode}, like vim.keymap.del.
The key goes back to the binding yours shadowed, or to maki's default.
Only your own bindings go. If another plugin holds {lhs}, nothing
changes and a warning names it. Only the modes you list are removed: a
binding set in { "n", "i" } and removed in "n" stays in "i".
Throws on an invalid mode or key.
Parameters:
{mode}(string|string[])"n","i", or a list of them.{lhs}(string) Key to unmap, in Vim notation.{opts?}(table?) Options:buffer(Buf) remove the binding set for this buffer instead of the global one.
Example:
maki.keymap.del({ "n", "i" }, "<C-t>")
maki.keymap.normalize()
maki.keymap.normalize({lhs})
Canonical spelling of {lhs}. Accepts every spelling set accepts and
returns the string a key event carries.
Parameters:
{lhs}(string) Key in any accepted notation.
Returns: (string|nil, string|nil) Canonical notation, or nil and an error.
Example:
local canon = maki.keymap.normalize("<Enter>") -- "<CR>"
maki.log
Structured logging for plugins.
Each call emits a tracing event tagged with the calling plugin's name.
Messages show up in maki's log output, which you can view with maki --log.
maki.log.info("ready")
maki.log.warn("something looks off")
maki.log.debug()
maki.log.debug({msg})
Emit a DEBUG-level log message. Useful for development and troubleshooting. The message is tagged with the plugin name automatically.
Parameters:
{msg}(string) Message to log.
Example:
maki.log.debug("loaded " .. #items .. " items")
maki.log.info()
maki.log.info({msg})
Emit an INFO-level log message. Good for normal operational events.
Parameters:
{msg}(string) Message to log.
Example:
maki.log.info("plugin initialized")
maki.log.warn()
maki.log.warn({msg})
Emit a WARN-level log message. Use for recoverable problems.
Parameters:
{msg}(string) Message to log.
Example:
maki.log.warn("config file missing, using defaults")
maki.log.error()
maki.log.error({msg})
Emit an ERROR-level log message. Use for failures that need attention.
Parameters:
{msg}(string) Message to log.
Example:
maki.log.error("failed to connect to API")
maki.model
The model behind the focused session. Good for a keybind that flips
between your two go-to models, or lifts thinking for one hard question.
Without an interactive UI every function returns
nil, "no interactive UI attached".
maki.model.get()
maki.model.get()
Reads the focused session's model, thinking level, and fast mode.
thinking comes back in the spelling set accepts, so a table from here
can go straight back in.
thinking_options lists named thinking choices, cheapest first, as
{name, tokens?, sends} per row. Request paths that use named thinking_fields
expose those levels without token counts. Toggle-only fields expose
adaptive and, when allowed, off. Otherwise the generic budget ladder applies.
tokens is absent on off and adaptive too. sends is the row the
request goes out as: the row's own name, or the level a model that does
not take this one snaps it to. The list is empty exactly when
supports_thinking is false.
thinking keeps the session's intent and delegation ceiling.
thinking_shown names the effective row to highlight, including snapped
effort levels and budgets sent as native levels or toggles. With declared
fields, a budget stays numeric only where the adapter forwards the count.
On the generic ladder, a model whose API has no adaptive mode leaves
adaptive out and shows its fixed level.
Declared effort fields keep adaptive separate because their fragments can
differ from the provider fallback.
Returns: (table|nil, string|nil) {spec, id, provider, thinking, thinking_shown, thinking_options, fast, supports_thinking, supports_fast}, or nil and an error.
Example:
local m = maki.model.get()
if m.spec ~= "anthropic/claude-opus-4-6" then ... end
for _, option in ipairs(m.thinking_options) do
print(option.name, option.tokens, option.sends)
end
maki.model.available()
maki.model.available()
Lists the model specs you can switch to: what the providers you are logged into offer, minus what your model policy blocks. The list fills in the background at startup, so right after launch it can still be empty.
Returns: (table|nil, string|nil) Array of "provider/id" specs, or nil and an error.
Example:
local specs = maki.model.available()
maki.model.set()
maki.model.set({opts})
Switches the focused session's model, thinking level, or fast mode. Fields
you leave out stay as they are, so this doubles as a thinking-only switch.
Answers with the new state, in the same shape get returns.
Requires the session_settings plugin permission.
Parameters:
-
{opts}(string|table) A model spec, or a table with any of:spec(string)"provider/id", as listed byavailable();thinking(string|number)"off","adaptive", an effort level
(
"minimal"to"max"), a token budget, or""to toggle it on and off;fast(boolean) Anthropic fast mode.
Returns: (table|nil, string|nil) The new state, or nil and an error.
Example:
maki.model.set("anthropic/claude-opus-4-6")
maki.model.set({ spec = "zai/glm-5", thinking = "high" })
maki.keymap.set({ "n", "i" }, "<M-t>", function() maki.model.set({ thinking = "" }) end)
maki.model.tier()
maki.model.tier({name}, {provider?})
The model maki uses for a tier, the same one a subagent asking for that tier gets. The first match wins:
- The user's pick for that tier in the
/modelpicker, from any provider. - The tier default within
provider, curated or set inproviders.toml. - The tier default of any provider.
assigned tells a pick apart from a default. Pass provider the way
subagents pass the session's provider.
Resolving a models.dev model can wait for that catalog to download, so
like get, this cannot run in a callback that must not yield.
Parameters:
{name}(string)"weak","medium","strong", or"compaction".{provider?}(string|nil) Provider slug to resolve within first.
Returns: (table|nil, string|nil) The model in the shape info returns, plus
assigned (boolean), true when you picked it for this tier. nil and nil
when no model fits the tier, nil and an error when the spec no longer
resolves.
Example:
local m = maki.model.tier("weak", maki.model.get().provider)
if m then maki.model.set(m.spec) end
maki.model.info()
maki.model.info({spec})
Resolve a model spec to everything maki knows about it: identity, tier, context window, and the price table the session would be billed by -- including rates resolved from provider config or the bundled catalog (e.g. subsidised custom providers), which the provider's own /v1/models endpoint may never report. Purely local -- no UI round-trip, no network -- so it also works from slash commands and headless embeddings.
Parameters:
{spec}(string)"provider/id", as listed byavailable().
Returns: (table|nil, string|nil) {spec, id, provider, provider_display, tier, subsidised_by?, context_window, max_output_tokens?, free?, pricing?}, or nil and an error.
free has three states: true when the model is known to cost nothing,
false when it is metered, and nil when no source ever quoted a rate.
Check ~= nil before trusting it.
subsidised_by names the subscription prepaying this provider (billed
cost is $0, the rates are the list-price reference). It sits at the top
level because it holds whether or not rates resolved.
pricing is present only when rates are known:
{input, output, cache_write, cache_read} in USD per million tokens,
plus optional fast = {input, output}.
Example:
local m, err = maki.model.info("anthropic/claude-opus-4-6")
if m and m.subsidised_by then print(m.subsidised_by, m.pricing.input) end
maki.net
HTTP, plain TCP, and Unix sockets for plugins.
request traffic goes over HTTPS (plain HTTP is upgraded). Private
and metadata IP addresses are blocked to prevent SSRF, including
after a redirect. Hosts listed in the net.allowed_private_hosts config
option are exempt, and so is a provider plugin's own origin (see
maki.net.request). Failed requests (5xx) are retried automatically.
Requests reuse a pool of clients, so calls to the same host share one keep-alive connection rather than pay a fresh handshake each time.
connect follows the same rules, but only reaches hosts the plugin
lists in net_hosts.
connect_unix and listen_unix exist on Unix only. They need the
run permission rather than net, because a plugin that can run
socat already reaches every local socket.
local res, err = maki.net.request("https://example.com")
if res then print(res.body) end
maki.net.request()
maki.net.request({url}, {opts?})
Make an HTTP request and return the response body. Plain http://
URLs are automatically upgraded to https://. Requests to private
or metadata IP addresses are blocked for safety, unless the host is
listed in net.allowed_private_hosts.
A request to the origin of a provider this plugin registered is sent
like the provider's chat requests: no address check, no https upgrade,
maki's user agent, and connect and stall timeouts instead of a total
one. This holds only for an origin the user set (<SLUG>_BASE_URL,
providers.toml) or a built-in provider's default.
{opts} fields:
method(string) HTTP verb, in any case (default"GET").headers(table) Header name/value pairs.body(string|buffer) Request body, sent as is.timeout(integer) Total timeout in seconds, max 120 (default 30, none on a provider's origin). 0 means the default.max_bytes(integer) Max response size in bytes, max 64 MiB (default 5 MiB). 0 means the default. The whole body is held in memory, so a bigger download belongs in a job such ascurl -o.retry(integer) Retries on 5xx errors (default 3).line_match(string) Regex. Keep only the response lines it matches. Filtering happens after the body is read, somax_bytesstill caps the transfer.
The response table has body (string), status (integer),
content_type (string) and headers (table). headers holds the final
response's headers under lowercase names, as in
res.headers["retry-after"]. Repeated headers are joined with , ,
which breaks set-cookie. A compressed response arrives decoded, without
its content-encoding and content-length. A failed response can go
straight to maki.provider.http_error.
body holds the raw bytes, so a binary download can go straight to
maki.fs.write. Tool results and maki.text.html_to_markdown turn
invalid UTF-8 into U+FFFD.
Requires the net plugin permission.
Parameters:
{url}(string) URL starting withhttp://orhttps://.{opts?}(table?) Request options (see above).
Returns: (table?, string?) Response table, or nil plus an error string.
Example:
local res, err = maki.net.request("https://httpbin.org/get")
if err then
print("failed: " .. err)
else
print(res.status, res.body)
end
maki.net.connect()
maki.net.connect({host}, {port}, {opts?})
Open a plain TCP connection to {host}:{port}, such as a dashboard or a language server running on your machine. There is no TLS.
The plugin must list the host in net_hosts, best with its port
("127.0.0.1:7777"): unlike request, net = true alone reaches
nothing. Private and loopback addresses are blocked like in request,
unless net.allowed_private_hosts allows them.
read and write yield, so a connection that stays open belongs in a
maki.async.spawn task. It closes on conn:close(), when the handle is
garbage collected, and when the plugin unloads.
{opts} fields:
timeout(integer) Connect timeout in seconds, max 60 (default 10). 0 means the default.
Requires the net plugin permission.
Parameters:
{host}(string) Host name or IP address.{port}(integer) Port to connect to.{opts?}(table?) Options (see above).
Returns: (maki.net.Conn?, string?) The connection, or nil plus an error string.
Example:
maki.async.spawn(function()
local conn, err = maki.net.connect("127.0.0.1", 7777)
if not conn then return maki.log.error(err) end
conn:write("hello\n")
while true do
local chunk = conn:read()
if not chunk then break end
handle(chunk)
end
conn:close()
end)
maki.net.connect_unix()
maki.net.connect_unix({path}, {opts?})
Connect to the Unix socket at {path}.
{opts} fields:
timeout(integer) Connect timeout in seconds, max 60 (default 10). 0 means the default.
Requires the run plugin permission.
Parameters:
{path}(string) Absolute path of the socket, or one starting with~/.{opts?}(table?) Options (see above).
Returns: (maki.net.Conn?, string?) The connection, or nil plus an error string.
Example:
maki.async.spawn(function()
local conn, err = maki.net.connect_unix("/run/user/1000/app/control.sock")
if not conn then return maki.log.error(err) end
conn:write("status\n")
print(conn:read())
conn:close()
end)
maki.net.listen_unix()
maki.net.listen_unix({path})
Listen on the Unix socket at {path}.
Fails if a file exists at {path}, so remove a stale socket first. The one
exception is a path this plugin already listens on, which it takes over,
so it can listen again after /reload. Keep the socket in a directory
only your user can write, so no other user can swap the file.
Requires the run plugin permission.
Parameters:
{path}(string) Absolute path of the socket, or one starting with~/.
Returns: (maki.net.Listener?, string?) The listener, or nil plus an error string.
Example:
maki.async.spawn(function()
local listener = assert(maki.net.listen_unix("/run/user/1000/app/inbox.sock"))
while true do
local conn = listener:accept()
if not conn then break end
print(conn:read())
conn:close()
end
end)
maki.net.Conn
A TCP or Unix socket connection, from maki.net.connect,
maki.net.connect_unix or Listener:accept.
read and write yield until done and can run at the same time.
The connection closes on :close(), when the handle is garbage
collected, and when the plugin unloads.
Conn:read()
Conn:read()
Wait for data and return what arrived, at most 64 KiB. Returns
nil, nil once the peer has closed its side.
Only one read at a time: a second read() while one is waiting returns
an error. A read and a write can run at the same time.
Returns: (string?, string?) Bytes read, or nil plus an error string, or nil, nil at end of stream.
Example:
local chunk, err = conn:read()
if err then return maki.log.error(err) end
if not chunk then print("peer closed") end
Conn:write()
Conn:write({data})
Send {data} and wait until all of it is written. Writes made while one is in flight wait their turn, so each goes out whole and in call order. A write that is cancelled or fails partway closes the connection, because the peer would read the next write as the rest of the cut one.
Parameters:
{data}(string) Bytes to send.
Returns: (boolean?, string?) true, or nil plus an error string.
Example:
local ok, err = conn:write(maki.json.encode(msg) .. "\n")
if not ok then return maki.log.error(err) end
Conn:close()
Conn:close()
Close the connection. A read or write in flight ends with an error. Extra calls do nothing.
maki.net.Listener
A Unix socket listener opened by maki.net.listen_unix.
It closes and removes its socket file on :close(), when the handle
is garbage collected, and when the plugin unloads.
Listener:accept()
Listener:accept()
Wait for the next client and return its connection. Returns nil, nil
once the listener is closed, also when it closes during the wait.
Only one accept at a time: a second one while one waits returns an
error.
Returns: (maki.net.Conn?, string?) The connection, nil plus an error string, or nil, nil once closed.
Example:
local conn, err = listener:accept()
if err then return maki.log.error(err) end
if not conn then print("listener closed") end
Listener:close()
Listener:close()
Stop listening and remove the socket file. A pending accept returns
nil, nil. Extra calls do nothing.
maki.provider
Providers implemented in Lua.
A registered provider works like a built-in one: its models show up in the picker, and its requests get the usual retries, pricing and usage accounting. The Providers guide covers writing one.
maki.provider.register({
slug = "acme",
display_name = "Acme",
codec = "openai",
base_url = "https://api.acme.com/v1",
api_key_env = "ACME_API_KEY",
models = { { prefixes = { "acme-large" }, tier = "strong" } },
})
maki.provider.register()
maki.provider.register({spec})
Register a provider this plugin implements. Its models are addressed as
<slug>/<model> and appear in the model picker and in /model.
Call it at the top level of the plugin file, since registration only works
while the plugin loads. The plugin needs a non-empty net_hosts list in its
plugin.toml. The Providers guide
walks through a full example.
A slug models.dev serves has to be one the package was granted: the
manifest lists it under providers, and the install approval covers it.
List every slug the package registers, so a name the catalog adds later
is already approved. A slug maki ships is reserved. See
granted slugs.
Set exactly one of codec or base. An unknown key, or an option the
chosen codec cannot honour, fails registration.
Every hook is optional and gets a ctx table as its first argument:
ctx.slug(string) The slug the hook serves.ctx.base_url(string?) The origin requests go to right now: an originauthreturned, then<SLUG>_BASE_URLorproviders.toml, then the declaredbase_url, nil when none is set. Build URLs from it so side calls follow a user who points the slug at a gateway.ctx.headers(table) The headers every request to the slug carries, under lowercase names.ctx.get_json(target)(function) A GET withctx.headers. Atargetstarting with/is appended toctx.base_url, an absolute URL is used as is. Never retried. Returns the decoded body, or nil plus an error the hook can return as its own.
A hook fails by returning nil, err, with err from ctx.get_json or
maki.provider.http_error. Maki then retries and honours retry-after as
it does for a built-in provider.
{spec} fields:
slug(string) Required. Letters, digits,_and-, starting with a letter or digit. See the slug rules.display_name(string) Required. Shown in the UI.codec(string) Wire format:"openai","openai-responses","anthropic"or"google".base(string) A native provider to borrow whole, e.g."ollama". Prefercodecfor a new provider.base_url(string) Default origin. Must behttps, orhttpon loopback, and its host must matchnet_hosts. Only withcodec. Abasemoves only to an origin theauthhook returns, so plans with abase_urlneed acodectoo.api_key_env(string) Env var holding the API key, re-read each time the provider is built. Sent asx-api-keyfor anthropic,x-goog-api-keyfor google, and a bearer token otherwise. Also lists the provider inmaki auth login, which saves the key. Needs theenvpermission.default_model(string) Model id without the slug, selected aftermaki auth login.login_url(string) Pagemaki auth loginopens to get a key.plans(table) List of{ key, display_name, base_url, default_model, login_url }formaki auth loginto offer.keyanddisplay_nameare required. A plan'sbase_urldefaults to the provider's and must matchnet_hosts. The choice is saved asplaninproviders.toml.family(string)"generic","claude","gpt","gemini","glm"or"synthetic". Applies to models without a row. Defaults to the provider behindcodecorbase.accepts_arbitrary_models(boolean) Assign tiers tolist_modelsresults. When false, tiers come only frommodels. This and the next two default to thebaseprovider's, or with acodectotrue,16384and128000.max_output_tokens(integer|false) Output cap for rows that leave it out and models without a row.falsesends no cap.context_window(integer) Context window for rows that leave it out and models without a row.pricing_schedule(table) Peak-hour pricing, as{ windows = { { 1, 4 }, ... }, multiplier = 2, weekdays_only = true }. Windows are{ start, end }UTC hours withendexclusive. Rowpricingis the off-peak rate.aperture(table){ path_prefix = "/v1" }routes Aperture models of this slug through this provider.docs(table){ features, discovery_note }for the generated Providers page.discovery_notereplaces the model table whenmodelsis empty.system_prefix(string) Text prepended to the system prompt. Thegooglecodec refuses it.openai(table) Options for the"openai"and"openai-responses"codecs, all optional. The responses codec takes only thinking options (withoutfield) andthinking_overrides, and refuses the rest:max_tokens_field(string) Body field carrying the output cap. Defaults tomax_tokens.include_stream_usage(boolean) Ask for usage on the stream. Defaults totrue.usage_cost(boolean) Price turns fromusage.coston the stream (in USD). Defaults tofalse.thinking(table) How the API spells reasoning effort. Without it, each model'sthinking_fieldsdecides.dialect(string) Required. One of"standard","codex","codex-5-1","coding-plan","gpt-5-6","gpt-6","prefer-high","high-only","glm","deepseek","anthropic-adaptive","gemini","tensorx","grok"or"ollama".effort(table) Replacesdialect's levels and off switch for every model, with the same fields as a model row'seffort. A row's owneffortwins over it.field(string) Body path for the effort. Dots nest, e.g."reasoning.effort". Defaults toreasoning_effort.requires_support(boolean) Send effort only to models that support thinking. Defaults tofalse.
headers(table) Sent with every request. They replace headers maki sets, and a header the credentials set wins.host,content-length,transfer-encodingandconnectionare refused.extra_body(table) Merged into every request body.thinking_overrides(table) Model id prefix to"no","yes"or"required", overriding the model table. Longest prefix wins.
session_id(table) Sends the session id with every request, as{ headers = { "x-affinity" } },{ body_field = "prompt_cache_key" }, or both. A listed header replaces one the credentials set. Thegooglecodec refuses it.replay_reasoning(boolean) Sends past assistant reasoning back asreasoninginput items, so a follow-up keeps what the model worked out earlier. Onlycodec = "openai-responses"accepts it, and only a provider that takes plaintext reasoning back should set it. Defaults tofalse.models(table) Static model rows, read once at registration. They describe models and add to the runtime list. See model rows.auth(function)function(ctx, purpose)returning{ base_url = ..., headers = { ... } }.purposeis"resolve"before the first request,"refresh"after a 401 on the newest credentials, or"reload"to re-read stored credentials after a login or another maki process changed them. Spend a refresh token only on"refresh". Omittingbase_urlkeeps the current one. A returned header replaces one maki oropenai.headerssets.list_models(function)function(ctx)returning model rows for a catalogue only known at runtime. Without it, the provider lists what its codec or base lists. Rows carryid,context_window,max_output_tokens,pricing,supports_thinking,supports_visionandtier, plus two optional fields.extrais any JSON value, handed back tobuild_bodyasopts.model_info.effortreplaces theopenai.thinkinglevels and off switch for this model:supportedlists the effort names the provider accepts, andsend_offistrueto send"none"for off orfalseto send nothing.build_body(function)function(ctx, body, model, opts)returning the body to send.opts.thinkingis the rendered effort level, nil when thinking is off.openaicodecs only.map_error(function)function(ctx, status, message)returning{ status = ..., message = ... }, or nil to keep the error. Retryability follows the returned status.fetch_usage(function)function(ctx)returning{ plan = ..., limits = { { label = ..., percentage = ..., reset_at = ..., detail = ... } }, by_model_today = { { model = ..., input_tokens = ..., output_tokens = ..., total_tokens = ..., spend_microdollars = ... } } }or nil. Onlylabelis required in a limit, andby_model_todayis optional.login(function)function(ctx). Defining it lists the provider inmaki auth login. Thisctxalso hasctx.print(text),ctx.prompt({ label = ..., secret = ... })andctx.open_url(url).logout(function)function(ctx), run bymaki auth logoutbefore Maki deletes the stored credentials itself. Only needed for work Maki cannot do, such as revoking a token upstream.
Requires the net plugin permission.
Parameters:
{spec}(table) Provider specification (see above).
Example:
maki.provider.register({
slug = "acme",
display_name = "Acme",
codec = "openai",
base_url = "https://api.acme.com/v1",
models = {
{ prefixes = { "acme-large" }, tier = "strong", context_window = 200000 },
},
auth = function(ctx)
local creds = maki.provider.auth.get(ctx.slug) or {}
return { headers = { Authorization = "Bearer " .. (creds.token or "") } }
end,
})
maki.provider.is_selected()
maki.provider.is_selected({slug})
Whether this package was granted {slug}: the manifest lists it under
providers and the install approval covers it. Kept from maki 0.6.3,
where multi-provider packages called it to skip the ones the user did not
select; it now answers from the same list.
Parameters:
{slug}(string) Provider name.
Returns: boolean
maki.provider.http_error()
maki.provider.http_error({res})
Turn a failed maki.net.request response into a provider error. A hook
returns it as return nil, err, and Maki handles it like a built-in
provider's failure: a 429 or 5xx is retried and retry-after sets the
wait. A hook that raises instead fails as a broken hook.
{res} fields:
status(integer) Required. The HTTP status.body(string) Required. Becomes the error message.headers(table) Onlyretry-afteris read, case-insensitively.
Parameters:
{res}(table) A response frommaki.net.request.
Returns: (userdata) A ProviderError. Opaque, but tostring renders it.
Example:
fetch_usage = function(ctx)
local res = assert(maki.net.request(ctx.base_url .. "/usage", { headers = ctx.headers }))
if res.status ~= 200 then
return nil, maki.provider.http_error(res)
end
return { limits = {} }
end
maki.provider.auth
Credential storage for the providers this plugin registered.
Each slug gets one JSON file at
~/.local/state/maki/auth/plugins/<slug>.json, with mode 0600, atomic
writes and a lock against other Maki processes. The plugin decides what
goes in it. A plugin can only reach slugs it registered itself.
maki.provider.auth.set("acme", { access_token = tok, expires = when })
local creds = maki.provider.auth.get("acme")
maki.provider.auth.clear("acme")
maki.provider.auth.get()
maki.provider.auth.get({slug})
Read the credentials this plugin stored for one of its providers. Returns nil when nothing was stored yet, for example before the first login.
Parameters:
{slug}(string) A provider slug this plugin registered.
Returns: (table?, string?) The stored credentials, or nil plus an error.
Example:
local creds = maki.provider.auth.get("acme")
if creds then print(creds.access_token) end
maki.provider.auth.set()
maki.provider.auth.set({slug}, {credentials})
Store credentials for one of this plugin's providers, replacing what was
there. Any table with string keys works, such as a token plus its expiry.
An auth hook can call it to save a refreshed token.
Parameters:
{slug}(string) A provider slug this plugin registered.{credentials}(table) Any table with string keys.
Returns: (boolean?, string?) True, or nil plus an error string.
Example:
local ok, err = maki.provider.auth.set("acme", { access_token = token })
if not ok then maki.log.error(err) end
maki.provider.auth.clear()
maki.provider.auth.clear({slug})
Forget the credentials stored for one of this plugin's providers.
Parameters:
{slug}(string) A provider slug this plugin registered.
Returns: (boolean?, string?) True, or nil plus an error string.
Example:
maki.provider.auth.clear("acme")
maki.session
Host session primitives. The interactive UI can run several sessions at once. These functions list, create, focus, rename, and delete them.
Without a UI, most functions return nil, "no interactive UI attached".
current, read, export, messages, windows, subagents,
notify and new without prompt or focus still work. ACP has no
focused session, so there current fails and the read functions need
session. Hook and event payloads carry it as session_id.
maki.session.list()
maki.session.list()
Lists sessions stored for the current project. Answered from a background scan, so a slow disk never blocks the UI.
Returns: (table|nil, string|nil) Array of {id, title, updated_at}, or nil and an error.
Example:
local stored, err = maki.session.list()
maki.session.live()
maki.session.live()
Lists the sessions currently running in this UI. Status is "working", "needs_input", or "idle". Background work a turn moved out keeps the session "working" until its result is in, with no "idle" in between.
Returns: (table|nil, string|nil) Array of {id, title, status, updated_at, focused}, or nil and an error.
Example:
local live, err = maki.session.live()
maki.session.current()
maki.session.current()
Returns the id of the focused session. Under maki -p and the sdk,
that is the one session they run.
Returns: (string|nil, string|nil) Session id, or nil and an error.
Example:
local id = maki.session.current()
maki.session.read()
maki.session.read({opts?})
One-call snapshot of a session: queue, usage, context, cost, mode, and
status. Reads the focused session, or the one you name in session: a
background tab, or a stored session nothing has open.
Metadata only, so it needs no permission. Not to be confused with the
session_read permission, which guards transcript content
(maki.session.export, maki.session.messages).
The returned table:
{
id, cwd, model, mode = "build" | "plan",
thinking, fast, -- nil under headless drivers
status = "idle" | "working" | "needs_input" | "stored",
focused, updated_at,
usage = { input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens },
context_size,
context_window, -- nil for a stored session
cost, -- nil for a stored session
queue = { count }, -- nil under headless drivers and for a stored session
title, -- nil under headless drivers
}
status is "stored" for a session nothing here runs. Its model is the
one it was saved with, resolved only when it opens.
usage and cost include subagent spend. context_size is the main
session's own, since a subagent runs its own window. There is no
list_cost here: the un-subsidised total for a run arrives on the
TurnEnd autocmd, and maki.model.info carries the rates behind it.
Parameters:
{opts?}(table?)session(string?) Session id, live or stored. Defaults to the focused one.
Returns: (table|nil, string|nil) Snapshot table, or nil and an error.
Example:
local s = maki.session.read()
if s.context_size > s.context_window * 0.8 then
maki.notify("context is nearly full")
end
maki.session.export()
maki.session.export({opts?})
Reads a session as the document maki session export prints, the same
table maki.session.new takes back:
{ format, model, mode, thinking, fast, title, facts, messages }
messages is what maki.session.messages returns. facts is the date,
working directory, model, instructions and hints the model was last told,
nil when the session never ran. A live session is read from memory,
unsaved messages included, any other from disk without claiming it, so a
session another maki has open can be read too.
JSON null comes back as maki.NIL and arrays are tagged, so
maki.session.export(...) encodes to the same document as the CLI file.
Copy it with maki.deepcopy before editing, which keeps both intact.
Requires the session_read plugin permission.
Parameters:
{opts?}(table?)session(string?) Session id, live or stored. Defaults to the focused one.
Returns: (table|nil, string|nil) The document, or nil and an error.
Example:
local doc = assert(maki.session.export({ session = maki.session.current() }))
maki.fs.write("/tmp/session.json", maki.json.encode(doc))
maki.session.messages()
maki.session.messages({opts?})
Reads a session's transcript, oldest first: everything the model has been sent so far, tool calls and results included. Read only.
Each message has the same shape as in the session file:
{ role = "user" | "assistant", kind, facts?, display_text?, receipts?, settles?, partial?, created_at?, content = { blocks } }
kind is "turn" for something the user or the model said,
"observation" for a report sent to the model as a user message, like
maki.session.notify, and "context_update" for a change since the
system prompt was built (date, model, plan mode, ...), which carries the
changed facts. display_text is what the UI shows instead of the
content: nil shows the content, "" hides the message (a nudge, a
compaction note). receipts lists the calls whose results in this
message moved to the background, and settles = { task, end } marks the
notice that answered one, with end one of "finished", "failed",
"cancelled" or "lost". partial has the same shape and marks a notice
that answered one piece early, like one call of a moved batch, and left
the receipt open. created_at is when the message was appended, in epoch
milliseconds, and nil for messages saved before the field existed.
content lists blocks:
{ type = "text", text }
{ type = "thinking", thinking, signature? }
{ type = "redacted_thinking", data }
{ type = "tool_use", id, name, input, thought_signature? }
{ type = "tool_result", tool_use_id, content, is_error?, loaded_tools? }
{ type = "image", source = maki.image.Image }
signature, thought_signature, data and loaded_tools are opaque:
pass them through untouched. A block type this build does not know comes
as its raw table. JSON null is maki.NIL.
A live session is read from memory, unsaved messages included, any other from disk.
Requires the session_read plugin permission.
Parameters:
{opts?}(table?) Options:session(string?) Session id, live or stored. Defaults to the focused one.window(string?)"current"or an archive id frommaki.session.windows. Defaults to the current window.last(integer?) only the newestlastmessages.
Returns: (table|nil, string|nil) Array of messages, or nil and an error.
Example:
local msgs = maki.session.messages({ last = 1 })
local last = msgs and msgs[1]
if last and last.role == "assistant" and last.content[1].type == "text" then
print(last.content[1].text)
end
maki.session.windows()
maki.session.windows({opts?})
Lists a session's transcript windows, newest first. [1] is the current
window. The rest are archives, each sealed by the compaction or rewind
that replaced its turns. Listing reads no transcript, so it stays cheap.
Each window is:
{
id = "current" | "<seq>", -- pass to `messages` or `subagents`
created_at, -- when the window began, in Unix seconds,
-- or nil if unknown
kind = "current" | "compaction" | "rewind" | "unknown",
}
Requires the session_read plugin permission.
Parameters:
{opts?}(table?) Options:session(string?) Session id, live or stored. Defaults to the focused one.
Returns: (table|nil, string|nil) Array of windows, or nil and an error.
Example:
for _, window in ipairs(assert(maki.session.windows())) do
print(window.id, window.kind, window.created_at)
end
maki.session.subagents()
maki.session.subagents({opts?})
Reads the subagent transcripts of one window, in spawn order. A
transcript belongs to the window holding the tool_use that started it.
Each entry is:
{
id, -- the `tool_use` id that spawned it, unique in the session
nr, -- 1-based number in the stored subagent list. Can skip
-- numbers and repeat across windows, so key on `id`
name, -- the task description that spawned it, or "subagent"
messages, -- same shape as `maki.session.messages`
}
Only the TUI stores subagent transcripts. Sessions run by maki -p, the
SDK or ACP give an empty list. Transcripts come from disk, so a running
subagent shows only the turns saved so far.
Requires the session_read plugin permission.
Parameters:
{opts?}(table?) Options:session(string?) Session id, live or stored. Defaults to the focused one.window(string?)"current"or an archive id frommaki.session.windows. Defaults to the current window.
Returns: (table|nil, string|nil) Array of subagents, or nil and an error.
Example:
for _, sub in ipairs(assert(maki.session.subagents())) do
print(sub.id, sub.nr, sub.name, #sub.messages)
end
maki.session.focus()
maki.session.focus({id})
Switches the UI to the session with {id}.
Parameters:
{id}(string) Session id, as returned bylist()orlive().
Returns: (boolean|nil, string|nil) true on success, or nil and an error.
Example:
local _, err = maki.session.focus(id)
maki.session.delete()
maki.session.delete({id})
Deletes a session and its stored history, cancelling it first if it is running. The focused session cannot be deleted.
Requires the session_write plugin permission.
Parameters:
{id}(string) Session id to delete.
Returns: (boolean|nil, string|nil) true on success, or nil and an error.
Example:
local _, err = maki.session.delete(id)
maki.session.new()
maki.session.new({opts?})
Creates a session from the document maki.session.export returns, or
from nothing.
Whatever the document leaves out is what a new tab would get: in the TUI
the focused tab's project, model, mode, thinking, fast and workflow, under
maki -p and sdk mode the project of the session they run, under ACP the
directory maki runs in. Outside the TUI no model is stored, so the session
opens on the default model. A document with messages gets no permissions
(yolo, session rules) from either side. Without messages it is a new tab
like Ctrl-N, which keeps the focused tab's yolo.
Without prompt or focus the session is only stored, and
maki.session.focus(id) opens it later. With either it opens in a tab.
A session is only stored once it has messages, so storing a document
with none left after repair fails. Pass focus to open a blank one
instead.
Headless drivers (maki -p, ACP) have nothing to open it in, so there
prompt and focus answer nil, "no interactive UI attached" and store
nothing.
History is repaired the way a resume repairs it (orphan tool results go,
a dangling final tool call is closed) and anything else wrong is refused
with its location, like messages[12].content[2]: ... (0-based, as in
the JSON document). A block of a known type that does not parse, or one
without a type, is refused too, while one of a type this build does not
know is kept. Thinking blocks and thought_signature are dropped: they
are bound to a system prompt the new session will not have. model is
stored as given and resolved when the session opens, falling back with a
warning like any resume.
Image sources may be a maki.image.Image or the
{ type = "base64", media_type, data } table maki.json gives. An empty
table where a list belongs (messages, a message's content) is refused,
since nothing tells it from an empty object: copy with maki.deepcopy,
which keeps the tag. Fields new does not know are ignored.
Requires the session_write plugin permission.
Parameters:
{opts?}(table?) Optional fields:messages(table) whatexportormessagesreturn. A user turn that starts with/or!, or isexit, needs theagentpermission too, since a rewind puts it back in the input for Enter to run.facts(table) whatexportreturns: the date, working directory, model, instructions and hints the model was last told.model(string) model spec. Defaults to the focused tab's in the TUI, else the default model when the session opens.mode(string) "build" or "plan".thinking(string) spelled like the thinking setting.fast(boolean) fast output mode, where the model supports it.title(string) else generated from the history.prompt(string) first user message to submit right away. Needs theagentpermission.focus(boolean) switch the UI to the new session.
Returns: (string|nil, string|nil) New session id, or nil and an error.
Example:
-- copy a session, keeping it in the background
local doc = assert(maki.session.export({ session = id }))
local copy, err = maki.session.new(doc)
-- start a fresh one right away
local id, err = maki.session.new({ prompt = "fix the tests", focus = true })
maki.session.prompt()
maki.session.prompt({text}, {opts?})
Sends {text} as a regular user prompt to a live session. The text is
never interpreted: slash commands, exit, and ! shell prefixes are
all sent to the model verbatim. If the session is currently streaming,
the prompt is queued and picked up when the agent reaches it.
Requires the agent and session_write plugin permissions.
Parameters:
{text}(string) The prompt to send. Must not be blank.{opts?}(table?) Optional fields: session (string) id of a live session; defaults to the focused one.
Returns: (string|nil, string|nil) "started" or "queued", or nil and an error.
Example:
local state, err = maki.session.prompt("run the tests", { session = id })
maki.session.notify()
maki.session.notify({text}, {opts?})
Reports {text} to a live session or one of its subagents without creating a user turn. The observation waits for the target's next agent run.
Requires the session_write plugin permission.
Parameters:
{text}(string) What to report. Must not be blank.{opts?}(table) Options:session(string) id of a live session.task(string?) id of a live subagent ofsession, asTurnCompletereports it; the report goes to that subagent instead of the session's own mailbox.wake(boolean) start a TUI turn when it next becomes idle (default false). Needs theagentpermission.display(string?) one-line note for the transcript, shown and saved when the session's agent run accepts the report. Whitespace collapses to single spaces and the note is cut to 256 bytes. Defaults to nothing; the model reads only {text}.
Returns: (boolean|nil, string|nil) true, or nil and an error.
Example:
maki.session.notify("[monitor] deploy failed", { session = id, wake = true })
maki.session.set_mode()
maki.session.set_mode({mode}, {opts?})
Switches a live session between plan and build mode. Entering plan mode allocates the session's plan file if it has none.
A session that is mid-plan answers the next prompt with another draft of
the plan. Set "build" first and that prompt implements it.
Requires the session_settings plugin permission.
Parameters:
{mode}(string) "build" or "plan".{opts?}(table?) Options:session(string) id of a live session, defaults to the focused one.
Returns: (boolean|nil, string|nil) true, or nil and an error.
Example:
maki.session.set_mode("build", { session = opts.session })
maki.session.prompt("Implement the plan at `" .. opts.path .. "`.", { session = opts.session })
maki.session.request_compact()
maki.session.request_compact({opts?})
Queues a compaction of a live session, the API behind /compact.
Answers once the request is queued, not when the summary lands: a
running agent compacts before its next request, an idle one when it
next runs. While one sits unclaimed, a repeat request fails.
agent.compact.before still steers or skips it, and sees it with
reason requested.
Requires the agent and session_write plugin permissions.
Parameters:
{opts?}(table) Options:session(string) id of a live session.task(string?) id of a live subagent ofsession, asTurnCompletereports it; that subagent's own conversation compacts.instructions(string?) guidance for this one summary, like/compact <text>.
Returns: (boolean|nil, string|nil) true once queued, or nil and an error.
Example:
maki.session.request_compact({
session = ctx:session_id(),
instructions = "keep the failing test names",
})
maki.session.set_title()
maki.session.set_title({opts})
Renames a session, live or stored.
Requires the session_settings plugin permission.
Parameters:
{opts}(table) Required fields: id (string) session to rename;title(string) the new title.
Returns: (boolean|nil, string|nil) true on success, or nil and an error.
Example:
local _, err = maki.session.set_title({ id = id, title = "refactor" })
maki.session.data_dir()
maki.session.data_dir({opts?})
Returns this plugin's data directory for a session,
state/sessions/data/<session>/<plugin>/. Deleting the session deletes
it. The directory may not exist yet, so create it with maki.fs.mkdir
before the first write. Writing there needs fs_write like any other path.
Parameters:
{opts?}(table?) Options:session(string?) Session id. Defaults to the session the calling agent serves (so a tool in a background tab gets that tab's directory), else the focused one.
Returns: (string|nil, string|nil) The directory path, or nil and an error.
Example:
local dir, err = maki.session.data_dir()
if dir then
maki.fs.mkdir(dir, { parents = true })
maki.fs.write(maki.fs.joinpath(dir, "scratch.md"), text)
end
maki.Timer
Handle returned by maki.defer_fn. Its :stop() cancels the
callback before it fires, which is what debouncing is built on.
Timer:stop()
Timer:stop()
Cancel the pending callback. Safe to call more than once, and does nothing once the callback has already run.
Example:
local h = maki.defer_fn(function() rebuild() end, 300)
h:stop()
maki.task
The subagents of the focused session and their transcripts. Tasks are
spawned by the task tool and addressed by an id that survives a reload.
Without an interactive UI every function returns
nil, "no interactive UI attached", except the ones that take a tool
handler's ctx: they reach the background tasks its agent moved.
maki.task.list()
maki.task.list()
Lists the focused session's chats in chat order. Entry 1 is always the main
chat, with id "main" and no status: its work is the session's own, and
maki.session.live() already reports that. The rest are subagents: one a
tool spawned has its tool call's id, one a plugin opened with
maki.agent.session has its session id and a
plugin field.
Returns: (table|nil, string|nil) Array of {id, session, name, focused, status?, plugin?, tool?, parent?, part?, wrapper?, started_at?, ended_at?, cost?}, or nil and an error.
status is "working", "idle" (a plugin task between prompts), "done",
"error" or "cancelled". session is the chat session that stop() asks for.
tool is the tool whose call the task runs, like "task" or "bash", and is
absent on a session a plugin opened on its own. parent is the id of the call
the task runs under, like a batch, which is listed only once it moved. part
is true for a piece listed with ctx:set_parts(): stopping it stops its whole
call, while a subagent the call started stops alone. wrapper is true for a
call that /tasks replaces with the tasks under it, so it gets no row and does
not count as running. started_at and ended_at are Unix seconds: when the
task started or moved, and when it finished. Tasks saved before they were
recorded lack them. cost is what a subagent billed so far, in dollars. The
main chat has none of the three.
Example:
for _, t in ipairs(maki.task.list() or {}) do
print(t.name, t.status or "main")
end
maki.task.focus()
maki.task.focus({id})
Shows a task's transcript, the way the chat cycling keys do. An id from another session returns an error instead of landing on the wrong task.
Parameters:
{id}(string) Task id, as returned bylist()."main"is the main chat.
Returns: (boolean|nil, string|nil) true on success, or nil and an error.
Example:
local _, err = maki.task.focus("main")
maki.task.remove()
maki.task.remove({id})
Deletes a finished task and its saved transcript. Refuses the main chat and running tasks. Deleting the focused task moves focus to the chat before it.
Requires the session_write plugin permission.
Parameters:
{id}(string) Task id, as returned bylist().
Returns: (boolean|nil, string|nil) true on success, or nil and an error.
Example:
local _, err = maki.task.remove("toolu_01")
maki.task.stop()
maki.task.stop({id}, {opts})
Stops a task in the focused session, the same way Esc in its tab does. A plugin task can be stopped while idle, even before its first prompt. The main chat, a finished task, or an unknown id returns an error.
Only the user may stop a task, so this works in a command the user typed
or a key they pressed. Tools, hooks, autocmds, maki.async tasks, and
commands run through maki.api.run_command get an error instead, or any
plugin could stop work that is not its own.
From a tool handler, stop(ctx, id) is the model's stop. It stops a
background task (a command or subagent) that the calling agent moved,
which is allowed because the tool call belongs to a turn the user started.
A subagent stopped this way ends its pending :prompt() with
"stopped by parent agent".
It waits up to 5 seconds for the final reply and returns it, and the agent
gets no notice of the end. A later reply reaches the agent as a quiet
notice instead. A subagent nested in a moved call, like a task in a
batch, stops alone and returns at once, because that call's result
reports what it did. A task another agent moved, a finished task or an
unknown id returns an error that lists the agent's running tasks.
Parameters:
{id}(string|LuaCtx) Task id, as returned bylist(). Or the handler's ctx, for the model's stop.{opts}(table|string)session(string), the chat session of thelist()row. If the user switched sessions since, this returns an error rather than stopping a task with the same id in the other session. With a ctx: the background task id.
Returns: (boolean|table|nil, string|nil) true on success, or nil and an
error. With a ctx, success is {name, output?, parent?}: the task's
name in /tasks, the final reply unless it was late, and the id of the
call a nested subagent ran in.
Example:
local _, err = maki.task.stop(task.id, { session = task.session })
-- in a tool handler
local stopped, err = maki.task.stop(ctx, input.id)
maki.task.send()
maki.task.send({ctx}, {id}, {text}, {opts?})
Messages a background subagent that the calling agent moved, the way the
task_message tool does. The subagent reads it as an interrupt from its
parent once its current turn ends, and one still waiting for a slot reads
it with its first prompt.
With interrupt it does not wait for the turn to end, nor for the calls
the subagent moved. The reply stops and running tools are cancelled (bash
returns what it printed so far), then the subagent reads the message and
carries on with its history intact. With no turn running the message
waits like any other.
{id} can also name a subagent nested in a call the agent moved, like a
task in a batch. The id of the call itself messages every subagent
still running in it.
Parameters:
{ctx}(LuaCtx) The tool handler's ctx.{id}(string) Task id, from its receipt.{text}(string) The message.{opts?}(table?) Optional fields:interrupt(boolean?) cut its current turn short. Default:false.
Returns: (table|nil, string|nil) {name}, the task's name in /tasks
(comma-separated when it reached several), or nil and
"no running background subagent with id <id>; running: ...".
Example:
local sent, err = maki.task.send(ctx, input.id, input.message)
if not sent then return { llm_output = err, is_error = true } end
return "Message queued for " .. sent.name .. "."
maki.task.messages()
maki.task.messages({ctx}, {id}, {opts?})
Reads the transcript of a background subagent that the calling agent
moved, oldest first, while it works. The messages have the shape
maki.session.messages returns. It takes the ids send(ctx, id) takes,
except the id of a call, since it reads one subagent. Works without an
interactive UI.
Requires the session_read plugin permission.
Parameters:
{ctx}(LuaCtx) The tool handler's ctx.{id}(string) Task id, from its receipt.{opts?}(table?)last(integer?) only the newestlastmessages.
Returns: (table|nil, string|nil) Array of messages, or nil and
"no running background subagent with id <id>; running: ...".
Example:
local msgs = maki.task.messages(ctx, input.id, { last = 1 })
local last = msgs and msgs[1]
if last and last.content[1].type == "text" then
print(last.content[1].text)
end
maki.text
Text utilities: format conversion, UTF-8 decoding and the fuzzy matcher the built-in pickers use.
local md = maki.text.html_to_markdown(html)
local text = maki.text.to_utf8(bytes)
local hits = maki.text.fuzzy_list("mrs", names, { limit = 10 })
maki.text.html_to_markdown()
maki.text.html_to_markdown({html})
Convert an HTML string to Markdown.
Useful for cleaning up web content fetched with maki.webfetch.
Invalid UTF-8 becomes U+FFFD.
Parameters:
{html}(string) HTML source text.
Returns: (string?, string?) Markdown text on success, or nil plus an error message.
Example:
local md, err = maki.text.html_to_markdown("<h1>Hello</h1><p>world</p>")
if err then return end
print(md) -- "# Hello\n\nworld"
maki.text.to_utf8()
maki.text.to_utf8({s})
Return {s} as valid UTF-8, with every invalid byte sequence replaced by
U+FFFD. Lua strings are bytes, and maki.net and maki.fs hand them over
as-is, so decode before measuring or cutting a body as text. An invalid
byte can grow to 3 bytes, so a cut made before decoding can triple in size.
Needs no plugin permission.
Parameters:
{s}(string) Bytes to decode.
Returns: (string) Valid UTF-8 text, s itself when it already is.
Example:
local resp = maki.net.request(url)
local text = maki.text.to_utf8(resp.body)
maki.text.fuzzy()
maki.text.fuzzy({needle}, {haystack}, {opts?})
Scores {needle} against {haystack} with the fuzzy matcher the built-in pickers use. {needle} is one pattern, spaces included.
Higher is better. Scores are only comparable across haystacks scored against the same needle. An empty needle matches everything with score 0.
The second return value lists where the match landed, in the same shape
as maki.fs.fuzzy_files: 1-based inclusive { from, to } byte ranges,
ascending, with adjacent characters merged. haystack:sub(from, to) is
the matched text.
Needs no plugin permission.
Parameters:
{needle}(string) What the user typed.{haystack}(string) The candidate to score it against.{opts?}(table?) Options:paths(boolean) rank {haystack} as a path, favouring the last segment, like the file picker. Off by default, like the model, command and list pickers.
Returns: (integer|nil, table|nil) Score and matched byte ranges, or nil when the needle does not match.
Example:
local score, at = maki.text.fuzzy("mrs", "maki-ui/src/main.rs", { paths = true })
if score then print(("maki-ui/src/main.rs"):sub(at[1][1], at[1][2])) end
maki.text.fuzzy_list()
maki.text.fuzzy_list({needle}, {haystacks}, {opts?})
Scores {needle} against every entry of {haystacks} and returns the matches, best first.
Ties keep their input order, so candidates you pre-sorted (by mtime, say)
stay in that order for an empty needle. index is the 1-based position in
{haystacks}, and highlights uses the byte ranges of fuzzy. Entries
that are not valid UTF-8 are skipped.
To rank files, use maki.fs.fuzzy_files instead. It queries the index
the host already keeps, so no candidate list crosses into Lua.
Needs no plugin permission.
Parameters:
{needle}(string) What the user typed.{haystacks}(table) Array of candidate strings.{opts?}(table?) Options:limit(integer) keep at most this many results.paths(boolean) rank candidates as paths, like the file picker. Off by default.highlights(boolean) also return where the query matched, off by default since it costs a second pass.
Returns: (table) Array of { text, index, score, highlights? }, best first.
Example:
for _, m in ipairs(maki.text.fuzzy_list(query, names, { limit = 10 })) do
print(m.text, m.score)
end
maki.treesitter
Tree-sitter parsing and query API.
Mirrors vim.treesitter from Neovim, so plugins can be shared between the two.
Start with get_parser() to parse source code, then use get_node_text() and
the query sub-module to extract information from the syntax tree.
local parser, err = maki.treesitter.get_parser(source, "lua")
local trees = parser:parse()
local root = trees[1]:root()
maki.treesitter.get_parser()
maki.treesitter.get_parser({source}, {lang})
Creates a LanguageTree for {source} using the grammar named {lang}.
This is the main entry point for parsing source code with tree-sitter.
Signature matches vim.treesitter.get_parser(), so Neovim plugins can be copy-pasted.
Parameters:
{source}(string) Source text to parse.{lang}(string) Language name, e.g."rust"or"lua".
Returns: (LanguageTree|nil, string|nil) Parser, or nil and an error message.
Example:
local parser, err = maki.treesitter.get_parser(src, "lua")
if err then print("error: " .. err) end
maki.treesitter.get_string_parser()
maki.treesitter.get_string_parser({source}, {lang})
Alias for get_parser. Use whichever name you prefer.
Parameters:
{source}(string) Source text to parse.{lang}(string) Language name.
Returns: (LanguageTree|nil, string|nil) Parser, or nil and an error message.
maki.treesitter.get_node_text()
maki.treesitter.get_node_text({node}, {source})
Gets the text that {node} covers in {source}. Useful when you have a captured node and need the actual source substring.
Parameters:
{node}(Node) The node whose text you want.{source}(string) Original source text the tree was parsed from.
Returns: (string) Substring covered by the node.
Example:
local text = maki.treesitter.get_node_text(node, source)
print(text)
maki.treesitter.get_node_range()
maki.treesitter.get_node_range({node})
Returns the range of {node} as four 0-based integers: start_row, start_col, end_row, end_col.
Parameters:
{node}(Node) The node to query.
Returns: (integer, integer, integer, integer) start_row, start_col, end_row, end_col.
Example:
local sr, sc, er, ec = maki.treesitter.get_node_range(node)
maki.treesitter.get_range()
maki.treesitter.get_range({node})
Returns a six-element table for {node}: {start_row, start_col, start_byte, end_row, end_col, end_byte}.
This gives you byte offsets in addition to row/column positions.
Parameters:
{node}(Node) The node to query.
Returns: (table) Six-element array: start_row, start_col, start_byte, end_row, end_col, end_byte.
Example:
local r = maki.treesitter.get_range(node)
print("bytes: " .. r[3] .. "-" .. r[6])
maki.treesitter.is_ancestor()
maki.treesitter.is_ancestor({dest}, {source})
Checks whether {dest} is an ancestor of {source} (or the same node). Walks up from {source} toward the root looking for {dest}.
Parameters:
Returns: (boolean)
maki.treesitter.is_in_node_range()
maki.treesitter.is_in_node_range({node}, {line}, {col})
Checks whether the 0-based position ({line}, {col}) falls inside {node}. Handy for cursor-position checks.
Parameters:
{node}(Node) Node to test against.{line}(integer) 0-based line number.{col}(integer) 0-based column number.
Returns: (boolean)
maki.treesitter.node_contains()
maki.treesitter.node_contains({node}, {range})
Checks whether {node} fully contains the given {range}.
Parameters:
{node}(Node) Node to test.{range}(table) Four-element array{start_row, start_col, end_row, end_col}.
Returns: (boolean)
maki.treesitter.get_node()
maki.treesitter.get_node({opts?})
Placeholder for cursor-based node lookup (not yet implemented, always returns nil).
Parameters:
{opts?}(table?) Options (currently unused).
Returns: (Node|nil) Always nil.
maki.treesitter.language
Language registry for tree-sitter grammars.
Mirrors vim.treesitter.language. Use these functions to register grammars,
map filetypes to languages, and inspect available node types.
maki.treesitter.language.add("lua")
maki.treesitter.language.register("lua", "luau")
maki.treesitter.language.add()
maki.treesitter.language.add({lang}, {opts?})
Registers {lang} for use with tree-sitter.
Call this to confirm a language grammar is available. Like
vim.treesitter.language.add. Custom grammar paths are not yet supported.
Parameters:
{lang}(string) Language name, e.g."rust".{opts?}(table?) Options table (thepathkey is not yet supported).
Returns: (boolean?, string?) true, or nil plus an error if {lang} is unknown.
Example:
if not maki.treesitter.language.add("lua") then return end
maki.treesitter.language.register()
maki.treesitter.language.register({lang}, {filetype})
Associates {lang} with one or more filetypes, so you can look up the right
parser language for a given filetype later with get_lang().
Parameters:
{lang}(string) Language name.{filetype}(string|table) A single filetype string or an array of filetype strings.
Example:
maki.treesitter.language.register("tsx", { "tsx", "jsx" })
maki.treesitter.language.get_lang()
maki.treesitter.language.get_lang({filetype})
Looks up the tree-sitter language name for {filetype}. Returns the registered language, or falls back to {filetype} itself if a grammar with that name exists. Returns nil when nothing matches.
Parameters:
{filetype}(string) Filetype to look up, e.g."ts".
Returns: (string|nil) Language name, or nil.
Example:
maki.treesitter.language.register("tsx", { "tsx", "jsx" })
local lang = maki.treesitter.language.get_lang("jsx") -- "tsx"
maki.treesitter.language.get_filetypes()
maki.treesitter.language.get_filetypes({lang})
Returns all filetypes that have been registered for {lang}.
Parameters:
{lang}(string) Language name.
Returns: (table) Array of filetype strings.
Example:
local fts = maki.treesitter.language.get_filetypes("tsx")
-- { "tsx", "jsx" }
maki.treesitter.language.inspect()
maki.treesitter.language.inspect({lang})
Returns metadata about the grammar for {lang}. Useful for debugging or discovering which node types and fields a grammar defines.
Parameters:
{lang}(string) Language name.
Returns: (table) Table with keys abi_version (integer), node_types (string[]), fields (string[]).
Example:
local info = maki.treesitter.language.inspect("lua")
print("ABI: " .. info.abi_version)
for _, nt in ipairs(info.node_types) do print(nt) end
maki.treesitter.query
Query compilation and lookup.
Mirrors vim.treesitter.query. Use parse() to compile a tree-sitter
query string into a Query object you can run against parsed trees.
local q = maki.treesitter.query.parse("lua", "(string) @str")
maki.treesitter.query.parse()
maki.treesitter.query.parse({lang}, {query})
Compiles a tree-sitter query string for {lang}. Throws if the language is unknown or the query has a syntax error.
Parameters:
{lang}(string) Language name, e.g."lua".{query}(string) Tree-sitter S-expression query.
Returns: (Query) Compiled query object.
Example:
local q = maki.treesitter.query.parse("lua", "(identifier) @id")
maki.treesitter.query.get()
maki.treesitter.query.get({lang}, {name})
Looks up a named built-in query for {lang} (not yet implemented, always returns nil).
Parameters:
{lang}(string) Language name.{name}(string) Query name, e.g."highlights".
Returns: (Query|nil) Query object, or nil if not found.
maki.treesitter.Query
A compiled tree-sitter query.
Get one by calling maki.treesitter.query.parse(lang, query_string).
Then use :iter_captures() or :iter_matches() to run it against a syntax tree.
local q = maki.treesitter.query.parse("lua", "(identifier) @id")
for idx, node, meta in q:iter_captures(root, source) do
print(node:type())
end
Query:iter_captures()
Query:iter_captures({node}, {source}, {start_row?}, {stop_row?})
Iterates over every capture matched by this query. Each call to the returned iterator yields (capture_index, node, metadata, match, active). Use this when you care about individual captures rather than whole pattern matches.
Parameters:
{node}(Node) Root node to search within.{source}(string) Source text the tree was parsed from.{start_row?}(integer) Only match rows >= this value (0-based).{stop_row?}(integer) Only match rows < this value (0-based).
Returns: (function) Iterator yielding (integer, Node, table, table, integer).
Example:
local q = maki.treesitter.query.parse("lua", "(identifier) @id")
for idx, node, meta in q:iter_captures(root, source) do
print(idx, node:type())
end
Query:iter_matches()
Query:iter_matches({node}, {source}, {start_row?}, {stop_row?})
Iterates over every full pattern match in this query. Each call to the returned iterator yields (pattern_index, captures, metadata, active) where captures is a table keyed by capture index. Use this when you need all captures for a pattern together.
Parameters:
{node}(Node) Root node to search within.{source}(string) Source text the tree was parsed from.{start_row?}(integer) Only match rows >= this value (0-based).{stop_row?}(integer) Only match rows < this value (0-based).
Returns: (function) Iterator yielding (integer, table, table, integer).
Example:
local q = maki.treesitter.query.parse("lua", "(function_declaration name: (identifier) @name)"
)
for pat, captures, meta in q:iter_matches(root, source) do
for cap_idx, nodes in pairs(captures) do
print(nodes[1]:type())
end
end
maki.treesitter.Tree
A parsed syntax tree.
Obtained from LanguageTree:parse() or LanguageTree:trees().
Call :root() to get the root node and start traversing.
local trees = parser:parse()
local root = trees[1]:root()
Tree:root()
Tree:root()
Returns the root node of this tree. This is where you start walking the syntax tree or running queries.
Returns: (Node) Root node.
Example:
local root = tree:root()
print(root:type()) -- e.g. "chunk" for Lua
Tree:copy()
Tree:copy()
Returns an independent copy of this tree. Edits to the copy will not affect the original.
Returns: (Tree) A new Tree with the same content.
maki.treesitter.Node
A single node in a parsed syntax tree.
Nodes are obtained from Tree:root(), navigation methods like :child(),
or from query captures. Each node knows its type, range, and children.
local root = tree:root()
print(root:type(), root:child_count())
for child, field in root:iter_children() do
print(child:type(), field)
end
Node:type()
Node:type()
Returns the grammar type name for this node, like "function_definition" or "identifier".
Returns: (string) Grammar type name.
Node:symbol()
Node:symbol()
Returns the numeric symbol id for this node's grammar type. Two nodes with the same type always share the same symbol id.
Returns: (integer) Symbol id.
Node:id()
Node:id()
Returns a unique string identifier for this specific node in the tree. Useful for deduplication or as a table key.
Returns: (string) Node identity string.
Node:range()
Node:range({include_bytes?})
Returns the range of this node as multiple return values.
Without {include_bytes}: start_row, start_col, end_row, end_col.
With {include_bytes} set to true: start_row, start_col, start_byte, end_row, end_col, end_byte.
Parameters:
{include_bytes?}(boolean) When true, byte offsets are included in the return values.
Returns: (integer, integer, integer, integer) Four values, or six when include_bytes is true.
Example:
local sr, sc, er, ec = node:range()
local sr, sc, sb, er, ec, eb = node:range(true)
Node:start()
Node:start()
Returns the start position of this node: row, column, and byte offset (all 0-based).
Returns: (integer, integer, integer) start_row, start_col, start_byte.
Node:end_()
Node:end_()
Returns the end position of this node: row, column, and byte offset (all 0-based).
Returns: (integer, integer, integer) end_row, end_col, end_byte.
Node:byte_length()
Node:byte_length()
Returns how many bytes this node spans in the source text.
Returns: (integer) Byte length.
Node:child()
Node:child({index})
Returns the child at position {index} (0-based), including anonymous nodes like punctuation. Returns nil if {index} is out of bounds.
Parameters:
{index}(integer) 0-based child index.
Returns: (Node|nil) Child node, or nil.
Node:named_child()
Node:named_child({index})
Returns the named child at position {index} (0-based), skipping anonymous nodes. Returns nil if {index} is out of bounds.
Parameters:
{index}(integer) 0-based named child index.
Returns: (Node|nil) Named child node, or nil.
Node:child_count()
Node:child_count()
Returns the total number of children, including anonymous nodes.
Returns: (integer) Child count.
Node:named_child_count()
Node:named_child_count()
Returns the number of named children (skipping anonymous punctuation nodes).
Returns: (integer) Named child count.
Node:children()
Node:children()
Returns all children (named and anonymous) as a Lua table.
Returns: (table) Array of Node.
Example:
for _, child in ipairs(node:children()) do
print(child:type())
end
Node:named_children()
Node:named_children()
Returns all named children as a Lua table, skipping anonymous nodes.
Returns: (table) Array of Node.
Node:iter_children()
Node:iter_children()
Returns an iterator function that yields (child, field_name) for every child.
The field name is nil for children that are not assigned to a grammar field.
Returns: (function) Iterator yielding (Node, string|nil).
Example:
for child, field in node:iter_children() do
if field then print(field .. ": " .. child:type()) end
end
Node:field()
Node:field({name})
Returns all children assigned to the grammar field {name} as a table.
For example, a function node might have a "name" or "body" field.
Parameters:
{name}(string) Field name defined in the grammar.
Returns: (table) Array of Node.
Example:
local bodies = node:field("body")
Node:parent()
Node:parent()
Returns the parent of this node, or nil if this is the root.
Returns: (Node|nil) Parent node.
Node:next_sibling()
Node:next_sibling()
Returns the next sibling (named or anonymous), or nil if this is the last child.
Returns: (Node|nil) Next sibling.
Node:prev_sibling()
Node:prev_sibling()
Returns the previous sibling (named or anonymous), or nil if this is the first child.
Returns: (Node|nil) Previous sibling.
Node:next_named_sibling()
Node:next_named_sibling()
Returns the next named sibling, skipping anonymous nodes. Returns nil at the end.
Returns: (Node|nil) Next named sibling.
Node:prev_named_sibling()
Node:prev_named_sibling()
Returns the previous named sibling, skipping anonymous nodes. Returns nil at the start.
Returns: (Node|nil) Previous named sibling.
Node:child_with_descendant()
Node:child_with_descendant({descendant})
Finds the direct child of this node that contains {descendant}. Returns nil if {descendant} is not actually inside this node.
Parameters:
{descendant}(Node) A node that may be a descendant.
Returns: (Node|nil) Direct child containing the descendant.
Node:descendant_for_range()
Node:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
Finds the smallest node inside this node that spans the given point range. Includes both named and anonymous nodes.
Parameters:
{start_row}(integer) Start row (0-based).{start_col}(integer) Start column (0-based).{end_row}(integer) End row (0-based).{end_col}(integer) End column (0-based).
Returns: (Node|nil) Smallest node covering the range, or nil.
Node:named_descendant_for_range()
Node:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
Like descendant_for_range, but only considers named nodes.
Parameters:
{start_row}(integer) Start row (0-based).{start_col}(integer) Start column (0-based).{end_row}(integer) End row (0-based).{end_col}(integer) End column (0-based).
Returns: (Node|nil) Smallest named node covering the range, or nil.
Node:named()
Node:named()
Returns true if this is a named node (not anonymous punctuation like , or ().
Returns: (boolean)
Node:extra()
Node:extra()
Returns true if this node is an "extra" (like a comment) that can appear anywhere in the grammar.
Returns: (boolean)
Node:missing()
Node:missing()
Returns true if this node is "missing", meaning it was inserted by the parser during error recovery.
Returns: (boolean)
Node:has_error()
Node:has_error()
Returns true if this node or any of its descendants contain a syntax error.
Returns: (boolean)
Node:has_changes()
Node:has_changes()
Returns true if this node has been marked as changed since the last parse.
Returns: (boolean)
Node:equal()
Node:equal({other})
Returns true if this node and {other} are the same node in the tree.
Parameters:
{other}(Node) Node to compare against.
Returns: (boolean)
Node:sexpr()
Node:sexpr()
Returns the S-expression (lisp-like) string for this node and its children. Handy for debugging the tree structure.
Returns: (string) S-expression.
Example:
print(node:sexpr()) -- e.g. "(identifier)"
Node:tree()
Node:tree()
Returns the Tree that this node belongs to.
Returns: (Tree) The owning tree.
maki.treesitter.LanguageTree
Manages parsing of a source string for a single language.
Obtained from maki.treesitter.get_parser() or maki.treesitter.get_string_parser().
Call :parse() to get the syntax tree, then use :root() on the tree to start walking nodes.
local parser, err = maki.treesitter.get_parser(source, "lua")
if not err then
local trees = parser:parse()
local root = trees[1]:root()
end
LanguageTree:parse()
LanguageTree:parse({range?})
Parses the source and returns a table containing the resulting Tree. The tree is cached, so calling this again is cheap.
Parameters:
{range?}(table) Unused. Accepted for API compatibility.
Returns: (table) Array with one Tree element.
Example:
local trees = parser:parse()
local root = trees[1]:root()
LanguageTree:lang()
LanguageTree:lang()
Returns the language name this parser was created with.
Returns: (string) Language name, e.g. "lua".
LanguageTree:children()
LanguageTree:children()
Returns child LanguageTrees for injected languages. Not yet implemented, always returns an empty table.
Returns: (table) Empty table.
LanguageTree:trees()
LanguageTree:trees()
Returns all parsed trees as a table (at most one for now).
Returns an empty table if parse() has not been called yet.
Returns: (table) Array of Tree.
LanguageTree:source()
LanguageTree:source()
Returns the source string this parser was created with.
Returns: (string) The original source text.
LanguageTree:is_valid()
LanguageTree:is_valid({exclude_children?}, {range?})
Checks whether the parse tree is still valid. Not yet implemented, always returns true.
Parameters:
{exclude_children?}(boolean) Unused.{range?}(table) Unused.
Returns: (boolean) Always true.
LanguageTree:for_each_tree()
LanguageTree:for_each_tree({fn})
Calls {fn} with (tree, nil) for the parsed tree.
Triggers a parse if the tree has not been parsed yet.
Parameters:
{fn}(function) Callback receiving(Tree, nil).
Example:
parser:for_each_tree(function(tree, _)
print(tree:root():type())
end)
LanguageTree:included_regions()
LanguageTree:included_regions()
Returns the regions this parser covers. Not yet implemented, always returns a table with one empty region.
Returns: (table) Array with one empty table.
LanguageTree:contains()
LanguageTree:contains({range})
Checks whether this parser covers the given {range}. Not yet implemented, always returns true.
Parameters:
{range}(table) Range to check (currently unused).
Returns: (boolean) Always true.
LanguageTree:destroy()
LanguageTree:destroy()
Drops the cached parse tree and frees its memory.
After calling this, the next parse() will re-parse from scratch.
maki.ui
Functions for building interactive UI. Create buffers to hold content, open floating or split windows to display them, highlight code, render markdown, and show status hints.
local buf = maki.ui.buf()
buf:line("hello from my plugin!")
local win = maki.ui.open_win(buf, { title = "Greeting", width = "50%", height = 5 })
Without a UI (maki -p, the sdk, ACP), buffers and the text helpers
still work. The calls that need a screen behave like this:
input,input_edit,input_decorate,input_submit, andactionon a built-in name returnnil, "no interactive UI attached". Plugin actions still run.open_editorreturns -1.flashwrites to the log.open_win,set_status_hint,set_window_title,set_mode,set_cursor_shapeandinput_ruleshave no effect.input_rulesstill throws on a bad rule, so a plugin's tests catch it.
Chat input
Plugins can read, style, change and send the chat input:
| Job | Call |
|---|---|
| Read the text, the cursor and the selection | input |
Style text by what it says, like a $skill:go chip | input_rules |
| Style text from plugin state, like ghost text or diagnostics | input_decorate |
| Change the text, the cursor or the selection | input_edit |
| Send the input, as Enter does | input_submit |
| React when the input changes | the InputChanged event |
| Switch to normal mode for a vim mode | set_mode, see Modes |
| Change the cursor shape, like a block in normal mode | set_cursor_shape |
A key that types TODO: at the cursor:
maki.keymap.set("i", "<M-t>", function(ev)
local st = ev.input
maki.ui.input_edit({
start = st.cursor, stop = st.cursor, text = "TODO: ",
version = st.version, session_id = st.session_id,
})
end)
When the look follows from the text, prefer input_rules. A rule runs
no Lua per keystroke, and its marks are right again after undo, redo,
a history recall or a chat switch.
The calls other than input_rules wait for the UI to answer. They work
from any callback, like a key handler or an autocmd. While your plugin
loads, they return nil and an error.
Moving the cursor or the selection needs the input
permission, because your next key lands at the
cursor. Changing the text needs agent and session_write as well,
what sending a message needs, because your next Enter sends it. This
covers input_edit and the built-in actions that
edit, like undo or a history recall. input_edit needs
session_read too. Without them they raise permission denied.
Reading the input needs session_read. This covers maki.ui.input,
ev.input and ev.text in a key handler, and a binding on a key that
types text, see
maki.keymap.set. Styling the input needs no
permission.
A plugin that may change the text may write any text. Before Enter runs or sends it, it checks each plugin that wrote it:
| Text starts with | Each plugin that wrote it needs |
|---|---|
! | run |
a / command | what that command needs from a plugin, see maki.api.run_command. Only the user can run some commands, like /yolo |
| anything else | agent and session_write, like input_submit |
If one of them falls short, Enter leaves the text where it is and the status bar names that plugin. The text becomes the user's again once it is sent or cleared, once another text replaces it, like a history recall, or once the user replaces all of it, like selecting everything and typing.
A draft a plugin wrote, restored after a restart, counts as written by
an unnamed plugin that holds agent and session_write at most,
which the status bar calls a plugin. So does a rewound or forked
turn that starts with / or !, or is exit.
Upgrading: input_edit needs input and session_read now, plus
agent and session_write to change the text, and the editing
built-in actions need input, agent and session_write. A binding
on a key that types text, like a or <Paste>, needs session_read
in any mode. A plugin.toml you wrote yourself grants them unless it
sets them to false. A package needs its author to add them, and you to approve
the package again.
Offsets and versions
Offsets count bytes from 0, and a range leaves out stop. So the
range start, stop is text:sub(start + 1, stop), and
text:sub(1, cursor) is everything before the cursor. A newline is
one byte.
A tab is one open session, named by its session_id. Its chats, the
main agent's and each subagent's, share one chat input, and each chat
keeps its own draft.
The calls work on the input of the focused tab. input, the
InputChanged event and ev.input of a key handler report its
version and session_id. Pass both to input_edit,
input_decorate and input_submit. Each tab counts versions from
zero, so a version alone cannot tell two tabs apart.
The user may type between your read and your call. input_edit and
input_decorate then move your offsets past what was typed, and
input_submit fails. All three fail when:
session_idnames a tab that is not focused.- The text was replaced since: a history recall, a chat switch that
swapped in another draft, a change made in
$EDITOR, or a send. - So much changed since
versionthat the offsets can no longer be moved.
input_edit and input_submit also fail while the chat input is
hidden, since the user could not read what gets sent. It is hidden
while a permission prompt, the plan form or a below split takes its
place, or while a picker, a modal or a focused plugin window covers
it. input_decorate still works then.
A failed call returns nil and an error message. Read the input again
and retry. Bad arguments, like a missing or an unknown field, throw.
Input marks
A mark styles a byte range of the input. input_rules puts one on
every match, and input_decorate and input_edit push marks at the
offsets you give. Marks and rules live in namespaces, named by ns.
Each plugin has its own namespaces, so two plugins can use the same
name. A mark has these fields:
| Field | Type | Effect |
|---|---|---|
start, stop | integer | The range, for pushed marks only. Without stop the mark is a point, which only virt_text shows. |
hl | string or table | A theme style name like "accent", or { fg, bg, bold, italic, underline, dim, strikethrough, reversed }. |
conceal | string | Text drawn in place of the range. "" hides it. |
reveal | string | "cursor" shows the raw text while the cursor is inside the range or on its edge. |
atomic | boolean | The cursor steps over the range, a selection takes it whole, and a delete that cuts into it removes all of it. |
virt_text | table | Spans drawn but never part of the text, { { text, hl? }, ... }. |
virt_text_pos | string | "eol" (default) draws virt_text after the line, "inline" before start. |
lang | string | Highlights the range as code in this language. |
The text of conceal and virt_text must not hold control
characters, newlines included. A mark never edits the text, so a send
carries the raw text, concealed ranges included.
Where marks overlap:
- A pushed mark draws over every rule, and a mark pushed later over one pushed earlier.
- A rule whose
nswas first set later draws over one set earlier. Replacing a rule keeps its place. - Within a tree-sitter rule, a later pattern draws over an earlier
one, and
markdown_inlineovermarkdown. - Within one pattern, a capture whose name first appears later in the
query draws over one that appears earlier. In
(inline_link (link_text) @text) @link,@linkdraws over@text.
Pushed marks move with the text: a range keeps covering the same words, and a point stays after text typed at it. A range is dropped once its text is gone, or when an edit lands inside it while it conceals or is atomic. Undo brings back the text without its marks, so undoing the delete of a chip shows its raw text. Marks stay with their draft across chat switches, go away when the plugin unloads, and are not saved.
maki.ui.buf()
maki.ui.buf({opts?})
Creates a new buffer for building UI content. The first buffer
created in a task becomes the "live" buffer, streamed to the UI while
the tool runs, which is what the tool's own output pane wants. A
float that opens during a tool call would take that spot away, so
create its buffer with { scratch = true }. It matches nvim's
nvim_create_buf(false, true). A buffer belongs to the task that
made it, so this throws at a plugin's top level.
Parameters:
{opts?}(table?) Optional.scratch(boolean) keeps the buffer out of the live slot, default false.
Returns: (Buf) Buffer handle.
Example:
-- The tool's output pane:
local out = maki.ui.buf()
out:line("hello world")
-- A float raised during a tool call needs its own buffer:
local toast = maki.ui.buf({ scratch = true })
toast:line("copied!")
maki.ui.theme_color()
maki.ui.theme_color({name})
Looks up a color the syntax theme names, such as "background",
"foreground" or "accent". For the styles the UI paints with, use
maki.ui.theme_style.
Parameters:
{name}(string) Syntax theme color name, e.g. "accent" or "background".
Returns: (string|nil) "#rrggbb" for a truecolor theme, a palette index as a
string like "4" when the theme names an ANSI color, or "default" for the
terminal's own color. Nil only when the name is unknown. Every form can be
passed straight to a span's fg/bg.
Example:
local accent = maki.ui.theme_color("accent")
if accent then
buf:line({ { "note", { fg = accent, bold = true } } })
end
maki.ui.theme_style()
maki.ui.theme_style({name})
Looks up a named style from the current theme. The names are the ones a span
already takes as a string ("dim", "item_selected", "keybind_section",
"diff_old", ...), so { text, "dim" } and theme_style("dim") paint the
same. Reach for the table when you need the parts, say to keep a style's
foreground over a background of your own. A span styled "cursor" also marks
the caret of a focused window, see the focus option of maki.ui.open_win.
Parameters:
{name}(string) Style name, the same spelling a span accepts.
Returns: (table|nil) {fg?, bg?, bold?, italic?, underline?, dim?, strikethrough?, reversed?}, ready to use as a span style. Colors are
spelled as in maki.ui.theme_color. Nil when the name is unknown, and an
empty table when the theme leaves that style unset.
Example:
local sel = maki.ui.theme_style("item_selected")
local dim = maki.ui.theme_style("dim")
buf:line({ { "note", { fg = dim.fg, bg = sel.bg } } })
maki.ui.highlight()
maki.ui.highlight({code}, {lang}, {opts?})
Syntax-highlights a chunk of source code. Returns a table of styled
lines that you can feed into a buffer. Each line is a list of
{text, style} spans where style is a {fg, bold?, italic?, underline?} table.
fg is "#rrggbb" for a truecolor theme, a palette index as a string like
"4" when the theme names an ANSI color, or "default" for the terminal's own
color. Pass the span straight to buf:line and it resolves correctly in
every case.
Parameters:
{code}(string) Source text to highlight.{lang}(string) Language identifier, e.g. "rust", "python".{opts?}(table?) Options. Fields:independent(boolean) highlight each line without cross-line context. Default false.prefix(string) the lines beforecode, used as token context. A trailing newline is optional. Only the nearest lines fitting within 16 KiB are parsed, so a comment or string opened before them is missed. Default "".
Returns: (table) Lines: { { {text, style}, ... }, ... }. Each style is {fg, bold?, italic?, underline?}.
Example:
local lines = maki.ui.highlight("fn main() {}", "rust")
for _, spans in ipairs(lines) do
buf:line(spans)
end
maki.ui.markdown()
maki.ui.markdown({text}, {width})
Renders Markdown into styled lines ready to display in a buffer.
Each span's style is either a named string ("bold", "heading",
"inline_code", etc.) or a {fg, bold?, italic?, underline?} table
for syntax-highlighted code blocks.
Parameters:
{text}(string) Markdown source.{width}(integer) Wrap width in columns.
Returns: (table) Lines: { { {text, style}, ... }, ... }.
Example:
local size = maki.ui.terminal_size()
local lines = maki.ui.markdown("# Hello\n\nSome **bold** text.", size.cols)
for _, spans in ipairs(lines) do
buf:line(spans)
end
maki.ui.humantime()
maki.ui.humantime({secs})
Formats a number of seconds into a short, human-friendly string. Useful for displaying elapsed time in status messages.
Parameters:
{secs}(integer) Duration in seconds.
Returns: (string) Human-readable duration, e.g. "1m30s".
Example:
maki.ui.humantime(90) -- "1m30s"
maki.ui.humantime(3661) -- "1h1m1s"
maki.ui.terminal_size()
maki.ui.terminal_size()
Returns the current terminal size. Handy for sizing floating windows or wrapping text to fit the screen.
Returns: (table) {cols, rows}, terminal width and height in characters.
Example:
local size = maki.ui.terminal_size()
local half_width = math.floor(size.cols / 2)
maki.ui.display_width()
maki.ui.display_width({text})
Returns the display width of a string in terminal cells, matching
how ratatui measures text.
Parameters:
{text}(string) The text to measure.
Returns: (integer) Number of display cells the text occupies.
Example:
local w = maki.ui.display_width("hello")
maki.ui.truncate_text()
maki.ui.truncate_text({text}, {max_width})
Splits a string at a display-cell boundary.
Parameters:
{text}(string) The text to split.{max_width}(integer) Maximum display cells for the head.
Returns: (table) {head = string, tail = string}.
Example:
local t = maki.ui.truncate_text("hello world", 5)
-- t.head == "hello", t.tail == " world"
maki.ui.set_mode()
maki.ui.set_mode({mode})
Switches the chat input to normal mode ("n") or insert mode ("i"),
like leaving and entering insert mode in Neovim.
The mode is global and stays until a plugin switches it again, apart from
the times Modes lists. It applies at once:
maki.fn.mode() returns it and the next key is matched against it. If
your plugin unloads while the input is in normal mode, maki switches it
back to insert mode.
Throws on any mode but "n" and "i".
Parameters:
{mode}(string)"n"or"i".
Example:
maki.keymap.set("n", "i", function() maki.ui.set_mode("i") end)
maki.ui.set_cursor_shape()
maki.ui.set_cursor_shape({shape}, {opts?})
Sets the shape of the chat input's cursor, like Neovim's guicursor.
Until a plugin calls this, the cursor looks the way you set up your
terminal. "default" restores that look, and so does unloading the
plugin that set the current shape.
Terminals set shape and blink together, so any shape other than
"default" also sets blinking. Leave out blink for a steady cursor.
Throws on an unknown shape or option.
Parameters:
{shape}(string)"block","bar","underline"or"default".{opts?}(table?) Optional.blink(boolean) blinks the cursor, default false.
Example:
maki.api.create_autocmd("ModeChanged", {
callback = function(ev)
maki.ui.set_cursor_shape(ev.data.new_mode == "n" and "block" or "bar")
end,
})
maki.ui.flash()
maki.ui.flash({msg})
Shows a short-lived message in the status bar, such as "copied!" or a transient warning. Without a UI, the message goes to the log.
Parameters:
{msg}(string) Message text.
Example:
maki.ui.flash("Copied to clipboard!")
maki.ui.action()
maki.ui.action({name})
Runs a built-in or plugin action by name, and returns whether it handled the request.
A built-in does what its default key does, so you can move it to another key:
| Built-in | What it does | false when |
|---|---|---|
"file_picker" | Opens the file picker | |
"search" | Opens message search | |
"help" | Opens or closes /help | |
"model_picker" | Opens the model picker | |
"plan_toggle" | Opens or closes the plan form | no plan is ready |
"plan_editor" | Opens the plan in your editor | there is no plan |
"edit_input" | Opens the chat input in your editor | |
"pop_queue" | Removes the first queued message | |
"prev_chat", "next_chat" | Shows the previous or next chat, with its own draft | |
"input_raw" | Switches the input between drawing what plugins conceal and showing the text under it, which is what gets sent | |
"undo", "redo" | Undoes or redoes one input edit | nothing to undo or redo |
"history_prev", "history_next" | Recalls the previous or next prompt | at either end of the history |
"newline" | Inserts a new line | |
"background" | Moves running calls to the background, like Ctrl+B | no call is running |
"undo", "redo", "history_prev", "history_next" and "newline"
edit the chat input, also in normal mode. They need the input, agent
and session_write permissions, see chat input, and throw
without them like any gated call. They return false in a finished subagent's chat, which has
no input. "pop_queue" needs session_write, because it throws away a
queued prompt. "background" needs agent, because each call it moves
wakes the chat with its result. The other built-ins need no permission.
A built-in runs in the UI after your earlier maki.ui calls, and
action waits for its answer. While your plugin loads, it returns nil
and an error at once.
A plugin action has a dot in its name, like "completion.accept". It
comes from maki.api.register_action, which
also says what permissions a caller needs. It runs at once, also while
your plugin loads, and action returns what it returned.
action returns nil and an error, which an if treats as not handled,
when:
- The action's plugin is not loaded.
- The action threw.
- Your plugin lacks a permission a plugin action needs. The status bar shows this too.
- A built-in runs without a UI.
It throws on a name that cannot be right: no dot and not a built-in, or one its loaded plugin never registered.
To try several actions on one key, see
Composing keys. To send the input,
use maki.ui.input_submit. For slash commands, see maki.api.run_command.
Parameters:
{name}(string) Action name, e.g."file_picker"or"completion.accept".
Returns: (boolean|nil, string|nil) Whether the action handled it, or nil and an error.
Example:
-- A vim plugin's undo in normal mode, which needs `input`, `agent` and `session_write`:
maki.keymap.set("n", "u", function() maki.ui.action("undo") end)
-- A key for a built-in that has none:
maki.keymap.set({ "n", "i" }, "<M-r>", function() maki.ui.action("input_raw") end)
maki.ui.open_editor()
maki.ui.open_editor({path})
Opens {path} in the user's $EDITOR (e.g. vim, nano) and suspends the
TUI until the editor exits. An exit code of 0 does not mean the user
saved: read the file back to see what changed.
Parameters:
{path}(string) File to open.
Returns: (integer) Editor exit code, or -1 if the editor failed to start or there is no UI.
Example:
local code = maki.ui.open_editor("/tmp/scratch.lua")
if code ~= 0 then
maki.ui.flash("editor exited with " .. code)
end
maki.ui.open_win()
maki.ui.open_win({buf}, {opts})
Opens a floating or split window that displays the contents of {buf}. Returns a Win handle you can use to receive events, update layout, and close the window when you are done.
A window belongs to one session and shows only while that session's tab is
focused. It closes when the session leaves its tab (/new, loading another
session, closing the tab), or right away if the session is not in any tab.
Parameters:
{buf}(Buf) Buffer to display.{opts}(table) Float configuration. Fields:width(integer|string) window width. Integer for absolute columns; "N%" for percent of terminal width. Default "60%".height(integer|string) window height. Integer for absolute rows; "N%" for percent of terminal height. Default "70%".row(integer?) row offset from the anchor corner. Negative values move up.col(integer?) column offset from the anchor corner.anchor(string) corner the (row, col) offset is relative to. One of "NW" (default), "NE", "SW", "SE". Or "input_caret", which sits the window beside the chat input cursor: the host takes the roomier side of the cursor, trims the height to what fits there, keeps the whole width on screen, and re-places it on every redraw, so it follows wraps, resizes and any modal taking focus.rowandcolshift the window off that spot, andstackgrows the next one away from the cursor. With no cursor on screen, because a form, a permission prompt or abelowsplit has taken the input box, it falls back to the centred default,rowandcolstill applying.border(string) border style. One of "rounded" (default), "single", "double", "none".title(string) text shown in the top border. Default "".title_pos(string) title alignment. One of "left" (default), "center", "right".footer(table) key-hint pairs shown in the bottom border. Each entry is {key, label}. A bordered float is widened to fit its title and footer, up to the screen width.zindex(integer) stacking order. Default 50.cursor_line(boolean) highlight the focused row. Default false.reserved_top(integer) rows reserved at the top of the content area. Default 0.reserved_bottom(integer) rows reserved at the bottom of the content area. Default 0.split(string) dock the window to an edge instead of floating. One of "above", "below", "left", "right", "panel", or "" (floating, default).order(integer) paint order among split windows at the same edge. Default 50.focus(boolean) whether the window takes keyboard focus on open. Default true. A focused window parks the terminal cursor on its first span styledcursor, which is where an input method (IME) shows the text being composed. With no such span on screen, the cursor is not parked.keys(table) keys this window takes while it is on screen, inmaki.keymapnotation, e.g.{ "<Tab>", "<CR>" }.maki.keymap.setwith{ buffer = buf }is the newer way to give a popup keys, with a handler per key, a mode, andev.fallback(). Requiresfocus = false, since a focused window already gets every key. A claimed key goes to this window'srecvand never reaches the chat input or globalmaki.keymap.setbindings. The window's buffer bindings are asked first. Claims are released automatically when the window closes, and a hidden or zero-size window claims nothing. Host pickers and the slash command palette take keys first while open over the window.<C-c>and<C-z>are refused.visible(boolean) whether the window is initially visible. Default true. Seewin:hide()for what hiding does.needs_input(boolean) whether the window means the session needs user input. Default false.stack(boolean) offset the window past the other stacked windows sharing its anchor, in open order, with a one row gap. Closing one moves the rest up. Floating windows only. Default false.session(string) id of the session that owns the window, e.g.ev.data.session_idorctx:session_id(). Default: the session of the running tool call, else the focused tab's. Amaki.async.runtask keeps the tool call's session, amaki.async.spawntask does not.
Returns: (Win) Window handle.
Example:
local buf = maki.ui.buf()
buf:line("Pick an option:")
local win = maki.ui.open_win(buf, {
title = "Menu",
width = "50%",
height = 10,
cursor_line = true,
footer = { { "q", "quit" }, { "Enter", "select" } },
})
maki.ui.set_status_hint()
maki.ui.set_status_hint({spans}, {opts?})
Shows your plugin's key hints in the status bar. Other plugins' hints are not affected. By default the hints show in every tab, even when set from a tool call. With opts.session they show only in that session's tab, replacing your every-tab hints there, and are cleared when the session leaves the tab.
Parameters:
{spans}(table|nil) Sequence of {key, label} pairs, e.g.{{"q", "quit"}, {"j", "down"}}. nil clears your hints foropts.session, or all your hints ifopts.sessionis not set.{opts}(table?)session(string): id of the session whose tab shows the hints, e.g.ev.data.session_idorctx:session_id(). Default: every tab.
Example:
maki.ui.set_status_hint({ {"q", "quit"}, {"j", "down"} })
-- later, clear them:
maki.ui.set_status_hint(nil)
-- Only in the tab of the session that is running a turn:
maki.api.create_autocmd("TurnStart", {
callback = function(ev)
maki.ui.set_status_hint({ {"Esc", "cancel"} }, { session = ev.data.session_id })
end,
})
maki.api.create_autocmd("TurnEnd", {
callback = function(ev)
maki.ui.set_status_hint(nil, { session = ev.data.session_id })
end,
})
maki.ui.set_window_title()
maki.ui.set_window_title({title})
Sets the terminal emulator's window title. Pass an empty string to clear it.
The title passes through tmux, GNU screen, and zellij untouched, and control characters are stripped, so model text cannot inject escape sequences into the terminal. On exit maki hands the title back to the shell, on terminals that support the title stack.
Parameters:
{title}(string) New window title, e.g."● 3/5 tests".
Example:
maki.ui.set_window_title("maki: " .. session_name)
-- Give the title back to the shell:
maki.ui.set_window_title("")
maki.ui.input()
maki.ui.input()
Reads the chat input of the focused tab.
The returned table has:
text(string) the whole value, newlines included.cursor(integer) byte offset of the cursor.anchor(integer|nil) byte offset of the other end of the selection, nil when nothing is selected. The selected bytes run frommath.min(anchor, cursor)tomath.max(anchor, cursor).version(integer) andsession_id(string), for the calls that write. See offsets and versions.
The table has no line or column. The example works them out. To open a
window at the cursor, pass anchor = "input_caret" to
open_win, an option unrelated to the selection
anchor here.
Requires the session_read plugin permission.
Returns: (table|nil, string|nil) The input state, or nil and an error without a UI.
Example:
local st = maki.ui.input()
local before = st.text:sub(1, st.cursor)
local line = select(2, before:gsub("\n", "")) -- 0-based
local col = #before:match("[^\n]*$") -- in bytes
maki.ui.input_rules()
maki.ui.input_rules({opts})
Sets a rule that marks the chat input in every tab, from a regex or a tree-sitter query. See chat input for when to use one.
Each ns of your plugin holds one rule. Calling again with the same
ns replaces it, and a call with only ns removes it. Rules go away
when the plugin unloads. A bad pattern, query or mark throws. Where
marks overlap, input marks says which draws on top.
A regex rule marks every match of pattern with mark. The pattern
uses Rust regex syntax.
Matching runs one line at a time, so a match never spans lines. The
pattern still sees the text before its line: \A is the start of the
input, $ the end of the line and (?m)^ the start of one. An empty
match marks a point. In conceal and the text of virt_text, $1 is
capture group 1, $0 the whole match and $$ a plain $.
A tree-sitter rule parses the input as lang and runs query on it, as
the treesitter fields below describe. Parsing runs in the background,
and until it catches up with typing, its marks move with the text like
pushed marks.
Parameters:
{opts}(table) Options:ns(string) the namespace.pattern(string|nil) the regex to match.mark(table|nil) the mark each match gets, withoutstartandstop. Required withpattern.treesitter(table|nil) a tree-sitter rule, in place ofpatternandmark.treesitter.lang(string) the language the input is parsed as, like"markdown".treesitter.query(string|table) the query forlang, or a table of language = query that gives each language in the input its own. The predicates are those ofmaki.treesitter.query, and#set!only takesinjection.language.- Code captured as
@injection.contentis in the language@injection.languagecaught, or the one#set! injection.languagenames. When the rule has a query for that language, the code is parsed again and that query runs there. Otherwise the code gets alangmark. - A
markdownrule runs itsmarkdown_inlinequery inside blocks by itself.
- Code captured as
treesitter.captures(table|nil) capture name = template, with the fields ofmark. Templates are drawn as written,$included.- Each capture needs a template, and each template a capture.
@injection.contentmay go without one.@injection.languageand names starting with_take none, since they only name the injected language or feed predicates.
Example:
-- Draw `$skill:go` as a ` go ` chip the cursor steps over:
maki.ui.input_rules({
ns = "skill",
pattern = [[\$skill:([\w-]+)]],
mark = { conceal = " $1 ", hl = "accent", atomic = true },
})
-- And remove it again:
maki.ui.input_rules({ ns = "skill" })
-- Bold text without its stars, unless the cursor is on it:
maki.ui.input_rules({
ns = "md",
treesitter = {
lang = "markdown",
query = { markdown_inline = [[ (strong_emphasis (emphasis_delimiter) @hidden) @strong ]] },
captures = {
hidden = { conceal = "", reveal = "cursor" },
strong = { hl = { bold = true } },
},
},
})
maki.ui.input_decorate()
maki.ui.input_decorate({opts})
Replaces all the marks your plugin has in namespace ns of the chat
input. Use it for looks that come from plugin state. When the look follows
from the text, a rule fits better.
Keep a look that tracks something live, like ghost text at the cursor, in
one namespace and replace it on InputChanged. Marks placed once, like
the chip over a paste, each need a namespace of their own.
A mark that the typing since version would have
dropped is skipped, so typing alone never fails the call.
Besides the cases in offsets and versions, the
call fails when a mark ends past the end of the text, an offset falls
inside a multi-byte character, or start is past stop.
Parameters:
{opts}(table) Options:ns(string) the namespace to replace.marks(table) list of marks,{}to clear the namespace.version(integer) the version the offsets were planned against.session_id(string) the tab the offsets were read from.
Returns: (table|nil, string|nil) { version }, the version the marks were placed on, or nil and an error.
Example:
maki.api.create_autocmd("InputChanged", {
callback = function(ev)
maki.ui.input_decorate({
ns = "ghost",
marks = { { start = ev.data.cursor, virt_text = { { "complete this", "dim" } }, virt_text_pos = "inline" } },
version = ev.data.version,
session_id = ev.data.session_id,
})
end,
})
maki.ui.input_edit()
maki.ui.input_edit({opts})
Replaces byte ranges of the chat input, as if the user had selected each
one and typed its text. All edits land as one change, with one new
version and one undo step.
Plan every range against the text at version, without counting the
other edits in the list. Ranges must not overlap, and no two may start
at the same offset. With edits = {} the call only moves the cursor or
the selection, or replaces the marks in ns, so it needs cursor,
anchor or marks. It makes no new version and no undo step.
Besides the cases in offsets and versions, an edit fails when:
- The user typed at or next to one of its ranges since
version. Two inserts at the same offset count, because no order is right for both. cursororanchorlands inside text changed sinceversion.strictis set andversionis not current.- A range ends past the end of the text, or an offset falls inside a multi-byte character.
Enter checks the text you write before it runs it, see
chat input. For marks alone, use input_decorate, which
needs no permission.
text is cleaned the way a paste is: tabs become spaces, carriage
returns become newlines, and other control characters are dropped. With
cursor, anchor or marks given, text that needs cleaning fails
instead, since their offsets would no longer match. ev.text of
<Paste> is already clean.
It also needs session_read, like maki.ui.input. Its answer and its
errors tell where the user typed since version, so a plugin could
learn the input from them.
Requires the input and session_read plugin permissions.
Parameters:
{opts}(table) Options:edits(table|nil) list of{ start, stop, text }tables,{}for none. Without it,start,stopandtextare read from {opts} as one edit.start(integer) byte offset where the range starts.stop(integer) byte offset where it ends. Equal tostartto insert.text(string) the new text,""to delete the range. Required.version(integer) the version the offsets were planned against.session_id(string) the tab the offsets were read from.cursor(integer|nil) byte offset to leave the cursor at, counted in the text the edits produce, as if nobody else had typed. Default is the end of the new text of the edit with the higheststart, or the cursor as it is wheneditsis empty.anchor(integer|nil) byte offset to select from, up tocursor, counted likecursor. Without it nothing stays selected.strict(boolean|nil) accept only the current version, instead of moving the edits past newer typing. Default false.marks(table|nil) marks to replace namespacenswith, counted likecursor. They appear together with the text. A mark that does not fit fails the whole edit.ns(string|nil) the namespace formarks. Required withmarks.
Returns: (table|nil, string|nil) { version, cursor } after the edit, or nil and an error. Pass this version to a call that follows.
Example:
-- Insert each paste under a chip, in a namespace of its own.
local pastes = 0
maki.keymap.set("i", "<Paste>", function(ev)
local st = ev.input
pastes = pastes + 1
local done = maki.ui.input_edit({
start = st.cursor, stop = st.cursor, text = ev.text,
ns = "paste" .. pastes,
marks = { { start = st.cursor, stop = st.cursor + #ev.text, conceal = "[pasted text]", atomic = true } },
version = st.version, session_id = st.session_id,
})
if not done then ev.fallback() end
end)
-- Wrap the selection in bold and keep the same words selected:
local st = maki.ui.input()
if not st.anchor then return end
local s, e = math.min(st.anchor, st.cursor), math.max(st.anchor, st.cursor)
maki.ui.input_edit({
edits = {
{ start = s, stop = s, text = "**" },
{ start = e, stop = e, text = "**" },
},
cursor = e + 2,
anchor = s + 2,
version = st.version,
session_id = st.session_id,
})
maki.ui.input_submit()
maki.ui.input_submit({opts})
Sends the chat input the way Enter does, / commands, ! lines, images,
the queue and the history included. Only a \ before the cursor differs:
Enter turns it into a new line, and input_submit sends it as it is.
Use it to send what a key handler wrote, since ev.fallback() on <CR>
refuses text that changed after the press, see
maki.keymap.set.
It sends only while the input still holds version, so what goes out is
the text your plugin planned against. After your own edit, pass the
version input_edit returned. In a key handler, ev.input.version is
the version at the press. Any other change makes the version stale, like
an edit of another plugin or a key that landed after the one second keys
wait for a handler.
A send needs the plugin permissions that doing the same thing directly needs:
- A message needs
agentandsession_write, likemaki.session.prompt, also when it waits in the queue or is the retry Enter sends after a login. - A
!or!!line needsrun. - A
/command needs whatmaki.api.run_commandneeds for it, so/yolo,/trust,/packupdateand/packdelalways fail.
Besides the cases in offsets and versions, the call fails, and the input stays as it is, when:
- The message queue has the keyboard after
/queue. - There is nothing to send, or the command palette is open with no command to run.
- Your plugin lacks a permission listed above.
- A plugin changed the text, and Enter would refuse it for that plugin, see chat input.
Parameters:
{opts}(table) Options:version(integer) the version of the text to send, frommaki.ui.input,ev.inputorinput_edit.session_id(string) the tab the version was read from.
Returns: (boolean|nil, string|nil) true once sent, or nil and an error.
Example:
-- Spell out `lgtm` before sending:
maki.keymap.set("i", "<CR>", function(ev)
local st = ev.input
local s, e = st.text:find("lgtm", 1, true)
local version = st.version
if s then
local r = maki.ui.input_edit({
start = s - 1, stop = e, text = "looks good to me",
version = st.version, session_id = st.session_id,
})
if not r then return end
version = r.version
end
maki.ui.input_submit({ version = version, session_id = st.session_id })
end)
maki.ui.Win
Handle to a floating or split window. You get one from
maki.ui.open_win(). Use recv() in a loop to handle keyboard
input, and call close() when done.
Fields: width, height (initial content dimensions in columns/rows),
visible (current visibility).
local win = maki.ui.open_win(buf, { title = "Demo" })
while true do
local ev = win:recv()
if not ev or ev.key == "q" then break end
end
win:close()
Win:recv()
Win:recv({timeout_ms?})
Waits for the next event from this window. Call this in a loop to build an interactive UI. Returns nil once the window is closed or the channel disconnects. Pass {timeout_ms} to also get {type="timeout"} events so your plugin can animate while idle.
Event tables by type:
{type="key", key}-- keypress. {key} is in canonicalmaki.keymapnotation:"q","<CR>","<Esc>","<C-n>","<S-Tab>".{type="resize", width, height}-- terminal was resized.{type="paste", text}-- bracketed paste.{type="close"}-- window was closed externally.{type="timeout"}-- no event arrived within {timeout_ms}.
Parameters:
{timeout_ms?}(integer) Max milliseconds to wait before a timeout event is returned.
Returns: (table|nil) Event table, or nil if the window has closed.
Example:
while true do
local ev = win:recv()
if not ev or ev.key == "q" then break end
if ev.type == "key" and ev.key == "<Down>" then
-- move cursor down
end
end
win:close()
Win:set_config()
Win:set_config({opts})
Updates the window layout on the fly. Only the fields you include in {opts} are changed, everything else stays the same.
Parameters:
{opts}(table) Partial float config. Accepted fields:title(string) border title text.title_pos(string) title alignment, "left", "center", or "right".footer(table) key-hint pairs{{key, label}, ...}shown in the bottom border.border(string) "rounded", "single", "double", or "none".anchor(string) corner origin, "NW", "NE", "SW", "SE", or "input_caret".width(integer|string) new width; integer or "N%".height(integer|string) new height; integer or "N%".zindex(integer) stacking order.cursor_line(boolean) highlight the focused row.reserved_top(integer) rows reserved at the top of the content area.split(string) edge docking, "above", "below", "left", "right", "panel", or "".order(integer) paint order among split windows.needs_input(boolean) whether the window means the session needs user input.
Example:
win:set_config({ title = "Updated!", width = "80%" })
Win:set_cursor()
Win:set_cursor({row})
Moves the highlighted cursor line to {row} (1-indexed). Only has a
visible effect when the window was opened with cursor_line = true.
Parameters:
{row}(integer) Target row, 1-indexed.
Example:
win:set_cursor(3) -- highlight the third line
Win:close()
Win:close()
Closes the window and frees its resources. Safe to call more than once. The window also closes automatically when the handle is garbage collected.
Example:
win:close()
Win:is_open()
Win:is_open()
Returns true if the window is still alive (not closed). Useful for checking before sending commands.
Returns: (boolean) true if open.
Example:
if win:is_open() then
win:set_config({ title = "still here" })
end
Win:show()
Win:show()
Makes the window visible again after it was hidden with hide().
Example:
win:show()
Win:hide()
Win:hide()
Hides the window without closing it. The window keeps its state
and buffer contents. Call show() to bring it back.
A hidden window of any kind takes no space, draws nothing and claims no keys. It still accepts commands and reports events.
Example:
win:hide()
-- do some work...
win:show()
Win:is_visible()
Win:is_visible()
Returns true if the window is both open and visible (not hidden).
Returns: (boolean) true if visible.
maki.ui.Buf
A content buffer that holds styled lines of text. Create one with
maki.ui.buf() and pass it to maki.ui.open_win() to show it in
a floating or split window.
local buf = maki.ui.buf()
buf:line("hello")
buf:line({ { "world", "bold" } })
Buf:line()
Buf:line({line})
Appends a single line to the end of the buffer. You can pass a
plain string for unstyled text, or a table of {text, style?} spans
for rich content. Style can be a named string like "bold" or
"keyword", or an inline table {fg?, bg?, bold?, italic?, underline?, dim?, strikethrough?, reversed?}.
Colors accept "#rrggbb", a terminal color name like "blue" or "light-gray",
or a palette index as a string like "4". Names must be spelled exactly,
hyphens included. Named and indexed colors are left for the terminal to
resolve, so they follow the user's palette. To mix a named style with colors
of your own, maki.ui.theme_style hands back its parts.
Invalid UTF-8 shows as U+FFFD.
Parameters:
{line}(string|table) Plain string, or a sequence of spans:{ {text, style?}, ... }.
Example:
buf:line("plain text")
buf:line({ { "ERROR", { fg = "#ff0000", bold = true } }, { " something broke" } })
Buf:lines()
Buf:lines({lines})
Appends several lines at once. Each entry uses the same format as
buf:line(), so you can mix plain strings and styled spans.
Parameters:
{lines}(table) Sequence of line values, each the same format accepted bybuf:line.
Example:
buf:lines({
"first line",
{ { "styled ", "bold" }, { "second line" } },
"third line",
})
Buf:set_lines()
Buf:set_lines({lines}, {opts?})
Replaces every line in the buffer with {lines}. Use this when you want to redraw the whole buffer, for example after the user toggles a view.
head counts the leading lines that say what the buffer is about, like
the command above a bash output. When the tool call moves to the
background, its row in the chat keeps only those lines, because the rest
streams in the task's tab. Without a head the row keeps just its title.
Parameters:
{lines}(table) Sequence of line values, each the same format accepted bybuf:line.{opts?}(table|nil) Options:head= number of leading lines (default 0).
Example:
buf:set_lines({ "new content", "replaces everything" })
buf:set_lines({ "cargo test", "──────", "running 3 tests" }, { head = 1 })
Buf:len()
Buf:len()
Returns how many lines the buffer currently holds.
Returns: (integer) Line count.
Example:
if buf:len() == 0 then
buf:line("(empty)")
end
Buf:get_lines()
Buf:get_lines()
Returns all lines in the buffer as a Lua table. Each line is a
sequence of {text, style?} spans, the same format buf:line()
accepts. Useful for reading back content, copying it to another
buffer, or round-tripping through set_lines().
Returns: (table) Sequence of lines.
Example:
local lines = buf:get_lines()
buf:set_lines(lines) -- round-trip
Buf:on()
Buf:on({event}, {callback})
Registers an event handler on the buffer.
Supported events:
- "click": fires when the user clicks a line. The handler receives a click-event table and may yield or mutate the buffer.
- "change": fires synchronously after every mutation (
line,lines,set_lines). Must not yield.
Calling on() again for the same event replaces the previous handler.
Parameters:
{event}(string) Event name: "click" or "change".{callback}(function) Handler function. For "click", receives a click-event table. For "change", receives no arguments.
Example:
buf:on("click", function(ev)
maki.ui.flash("Clicked row " .. ev.row)
end)
Buf:click()
Buf:click({ev})
Programmatically fires the buffer's click handler with event {ev}. Does nothing if no click handler is registered. Useful for testing or simulating user interaction from code.
Parameters:
{ev}(table) Click event table passed to the handler.
Example:
buf:click({ row = 1 })
Buf:blit()
Buf:blit({fb}, {width}, {height}, {opts?})
Replaces the whole buffer with a pixel frame drawn as "▀" cells.
Each cell's foreground is the top pixel and its background the
bottom one, so one text line fits two pixel rows. When {height} is
odd the last line leaves its background unset and the terminal
default shows through.
{fb} is a Luau buffer of raw pixel bytes in row-major order,
top-left origin. Its size must be exactly
width * height * bytes_per_pixel for the chosen format, otherwise
the call throws. A mismatch usually means a wrong width or format,
and an early error beats hunting down a garbled frame.
Formats: "rgb" is the default at 3 bytes per pixel. "rgba" and
"bgra" take 4 bytes per pixel and ignore the 4th byte. "bgra" is
what a little-endian uint32 holding 0xRRGGBB looks like in
memory, the layout doomgeneric uses for its framebuffer.
char swaps the "▀" glyph for another one column wide string,
e.g. "█" when only the foreground color should show. The
foreground still comes from the top pixel and the background from
the bottom one, whatever the glyph.
Parameters:
{fb}(buffer) Raw pixel bytes.{width}(integer) Frame width in pixels, > 0.{height}(integer) Frame height in pixels, > 0.{opts?}(table|nil) Options:format= "rgb"|"rgba"|"bgra",char= one column wide string.
Example:
local fb = buffer.create(160 * 100 * 3)
buffer.writeu8(fb, (y * 160 + x) * 3, 255) -- red channel
buf:blit(fb, 160, 100)
buf:blit(fb32, 160, 100, { format = "bgra", char = "█" })
maki.uv
System and environment utilities, modelled after vim.uv.
Provides access to the working directory, home directory, and environment variables. None of these functions throw.
Filesystem location queries (cwd, os_homedir) need fs_read, while
os_getenv reads the process environment, where secrets live, so it needs
env.
local home = maki.uv.os_homedir()
maki.uv.cwd()
maki.uv.cwd()
Return the current working directory as an absolute path. Like vim.uv.cwd.
Requires the fs_read plugin permission.
Returns: (string?) Current working directory, or nil if it cannot be determined.
Example:
local cwd = maki.uv.cwd()
if cwd then print("working in: " .. cwd) end
maki.uv.os_homedir()
maki.uv.os_homedir()
Return the current user's home directory. Like vim.uv.os_homedir.
Requires the fs_read plugin permission.
Returns: (string?) Home directory path, or nil if it cannot be determined.
Example:
local home = maki.uv.os_homedir() -- e.g. "/home/user"
maki.uv.os_getenv()
maki.uv.os_getenv({name})
Look up the environment variable {name}. Like vim.uv.os_getenv.
Returns nil when the variable is not set.
Requires the env plugin permission.
Parameters:
{name}(string) Name of the environment variable.
Returns: (string?) Variable value, or nil if not set.
Example:
local editor = maki.uv.os_getenv("EDITOR") or "vi"
maki.version
Version parsing and comparison with the same API as Neovim's
vim.version. maki.version() returns the running maki version as a
version table.
Every function except parse takes a version table, a
{major, minor, patch} tuple or a string, parsed loosely like
maki.version.parse. A string that does not parse returns
(nil, err). Any other type raises a Lua error.
if maki.version.ge(maki.version(), "0.7.0") then ... end
maki.version.parse()
maki.version.parse({version}, {opts?})
Parse a version string, such as "1.2.3-rc.1+build.5", into a version
table with major, minor, patch, and optional prerelease and build.
[1], [2] and [3] alias the numbers. Two version tables compare with
==, <, <=, > and >=, and tostring prints one.
Parsing is loose by default, like Neovim, so "v1.2", "tmux 3.2a" and
"git version 2.43.0" all parse. The version starts at the first digit and
ends at whitespace. Missing minor and patch are 0. Trailing text is dropped
unless it is a valid SemVer -prerelease or +build suffix.
Parameters:
{version}(string) Version string to parse.{opts?}(table?) Options:strict(boolean) only accept a full SemVer 2.0.0 string. Off by default.
Returns: (table?, string?) Version table.
Example:
local v = maki.version.parse("1.0.1-rc1+build.2")
print(v.major, v.prerelease, tostring(v)) -- 1 rc1 1.0.1-rc1+build.2
maki.version.parse("git version 2.43.0") -- 2.43.0
maki.version.parse("1.0", { strict = true }) -- nil, invalid version: "1.0"
maki.version.cmp()
maki.version.cmp({v1}, {v2})
Compare two versions by SemVer precedence. Build metadata is ignored, and a prerelease sorts before its release.
Parameters:
{v1}(table|string) First version.{v2}(table|string) Second version.
Returns: (integer?, string?) -1, 0 or 1 when v1 is lower, equal or higher.
Example:
maki.version.cmp({1, 0, 3}, "0.2.1") -- 1, nil
maki.version.cmp("1.2.3-rc.2", "1.2.3-rc.10") -- -1, nil
maki.version.cmp("v1.2", "1.2.0") -- 0, nil
maki.version.eq()
maki.version.eq({v1}, {v2})
Whether v1 == v2, by maki.version.cmp rules.
Parameters:
{v1}(table|string) First version.{v2}(table|string) Second version.
Returns: (boolean?, string?) The result.
maki.version.lt()
maki.version.lt({v1}, {v2})
Whether v1 < v2, by maki.version.cmp rules.
Parameters:
{v1}(table|string) First version.{v2}(table|string) Second version.
Returns: (boolean?, string?) The result.
maki.version.le()
maki.version.le({v1}, {v2})
Whether v1 <= v2, by maki.version.cmp rules.
Parameters:
{v1}(table|string) First version.{v2}(table|string) Second version.
Returns: (boolean?, string?) The result.
maki.version.gt()
maki.version.gt({v1}, {v2})
Whether v1 > v2, by maki.version.cmp rules.
Parameters:
{v1}(table|string) First version.{v2}(table|string) Second version.
Returns: (boolean?, string?) The result.
maki.version.ge()
maki.version.ge({v1}, {v2})
Whether v1 >= v2, by maki.version.cmp rules.
Parameters:
{v1}(table|string) First version.{v2}(table|string) Second version.
Returns: (boolean?, string?) The result.
maki.version.last()
maki.version.last({versions})
Return the highest version in a list, as the element itself.
Parameters:
{versions}(table) List of versions.
Returns: (any, string?) The highest element, or nil for an empty list.
Example:
maki.version.last({ "1.9.0", "1.10.0", "1.2.0" }) -- "1.10.0", nil
maki.yaml
YAML encoding and decoding. Works the same way as maki.json,
but for YAML formatted strings.
local t = maki.yaml.decode("greeting: hello")
print(t.greeting)
maki.yaml.encode()
maki.yaml.encode({value})
Turn a Lua value into a YAML string. Most Lua types work, but circular references will return an error.
Parameters:
{value}(any) Lua value to encode.
Returns: (string?, string?) YAML string, or nil plus an error.
Example:
local s, err = maki.yaml.encode({ name = "maki", tags = { "ai", "agent" } })
print(s)
maki.yaml.decode()
maki.yaml.decode({str})
Parse a YAML string into a Lua value. Mappings become tables and sequences become 1-indexed arrays.
Parameters:
{str}(string) YAML string to decode.
Returns: (any?, string?) Decoded value, or nil plus an error.
Example:
local t, err = maki.yaml.decode("name: maki\nversion: 1")
print(t.name) -- maki
Shared helper modules
These ship inside maki; require them from any plugin. Small modules are
shown as full source, larger ones as their public interface.
require("maki.color")
local M = {}
function M.lerp(from, to, t)
local fr, fg, fb = from:match("^#(%x%x)(%x%x)(%x%x)$")
local tr, tg, tb = to:match("^#(%x%x)(%x%x)(%x%x)$")
if not fr or not tr then
return nil
end
fr, fg, fb = tonumber(fr, 16), tonumber(fg, 16), tonumber(fb, 16)
tr, tg, tb = tonumber(tr, 16), tonumber(tg, 16), tonumber(tb, 16)
local r = math.floor(fr + (tr - fr) * t + 0.5)
local g = math.floor(fg + (tg - fg) * t + 0.5)
local b = math.floor(fb + (tb - fb) * t + 0.5)
return string.format("#%02x%02x%02x", r, g, b)
end
function M.dim(color, factor)
local background = maki.ui.theme_style("background")
local bg = background and background.bg
return bg and M.lerp(color, bg, factor)
end
return M
require("maki.dir_listing")
-- Shared directory listing for index and list plugins, so every caller
-- shows a directory the same way. Listing also loads the directory's
-- instruction files onto the call.
function M.list(path, ctx)
function M.view(text, ctx)
require("maki.fuzzy_replace")
M.NO_MATCH = "old_string not found in file"
M.MULTIPLE_MATCHES = "old_string matches multiple locations; add surrounding context to make it unique"
M.EMPTY_OLD_STRING = "old_string must not be empty"
-- Replace {old_string} with {new_string} in {content}, tolerating small
-- whitespace and indentation drift. Returns the new content, or nil plus
-- one of the error constants above.
function M.replace(content, old_string, new_string, replace_all)
require("maki.list_nav")
-- Moves a cursor through a list, so every picker answers the same keys. It
-- keeps no state: you pass the key, the cursor row and a function that moves
-- the cursor. The list and the drawing stay yours.
--
-- Call it after your own keys, so a key you bind wins:
--
-- if key == "<CR>" then
-- open(cursor)
-- elseif not ListNav.handle_key(key, cursor, { count = #rows, page = height }, select_row) then
-- input:handle_key(key)
-- end
-- For a list under a text input. It has no letters, because the input needs
-- them.
ListNav.KEYS = table.freeze({
["<Up>"] = "up",
["<Down>"] = "down",
["<PageUp>"] = "page_up",
["<PageDown>"] = "page_down",
})
-- Adds j and k, for a list without a text input.
ListNav.VIM_KEYS = table.freeze({
["<Up>"] = "up",
["<Down>"] = "down",
["<PageUp>"] = "page_up",
["<PageDown>"] = "page_down",
j = "down",
k = "up",
})
-- Calls {move_to}(row) for a navigation {key} and returns whether {key} is
-- one, so you know when to pass it on. It returns true even when the cursor
-- cannot move, so an arrow key never types into a filter. {move_to} only gets
-- a selectable row that exists.
--
-- {opts}:
-- count: rows in the list
-- page: rows a page moves, usually the visible height. Defaults to {count}
-- wrap: false stops Up and Down at the ends. Pages never wrap
-- selectable: function(row) -> boolean, false for rows to skip, like
-- spacers or headings
-- keys: key -> "up"|"down"|"page_up"|"page_down", with keys spelled as
-- `maki.keymap.normalize` returns them. Defaults to `ListNav.KEYS`
function ListNav.handle_key(key, cursor, opts, move_to)
require("maki.list_picker")
-- Draws the filter query and its blank spacer into {lines}, pins that height on
-- {win} and returns it, which is also the first scrollable line. Drawing and
-- pinning belong together: a query that wraps, or one pasted with a newline,
-- makes the header taller than a picker would guess, and a reserved_top guessed
-- elsewhere then mis-scrolls the list.
function ListPicker.render_header(win, lines, input, prefix, inner)
-- Open a fuzzy-filter picker in a floating window and block until the user
-- decides.
--
-- {items} is a list of strings or of
-- { label, detail?, section?, section_detail? } tables. A detail is a string, or
-- a list of { text, style } parts when the right of a row needs more than one
-- color. Mark one part `elastic = true` and that is the part a narrow row cuts,
-- leaving the parts after it whole.
--
-- {opts}:
-- title, footer, cursor (initial index)
-- submit_keys: extra submit keys besides <CR>
-- action_keys: keys that close the picker and report themselves, like { "R" }
-- for a refresh binding. Use uppercase keys, lowercase ones keep feeding
-- the filter
-- live_keys: { [key] = function(item|nil) -> items|nil }, keys that swap the
-- list in place, keeping the typed query. Called with the selected item, or
-- nil when nothing matches, and returning nil leaves the list alone.
-- Handlers run inside the render loop, so keep them cheap and hand anything
-- slow to an action_key
-- key: function(item) -> string|nil, a row's identity. Rows sharing the
-- selected row's key are tinted, and the cursor follows its key across a
-- live swap
--
-- A key you bind overrides the built-in keys, except <Esc> and <C-c>, which
-- always close. Keys you pass go through `maki.keymap.normalize`, so
-- `"<Enter>"` and `"<CR>"` are the same binding. An invalid key is dropped
-- with a warning.
--
-- Returns { type = "choice"|"delete", index, item },
-- { type = "key", key, index?, item? } or { type = "close" }. Prefer {item},
-- since {index} points into an {items} a live swap may have replaced.
function ListPicker.open(items, opts)
ListPicker.split_words = split_words
ListPicker.matches = matches
ListPicker.highlight_spans = highlight_spans
ListPicker.range_spans = range_spans
ListPicker.clamp_parts = clamp_parts
require("maki.output_limits")
-- Shared per-tool output limit options, so the tools that support them
-- cannot drift apart.
M.DEFAULT_MAX_LINE_BYTES = DEFAULT_MAX_LINE_BYTES
M.FULL_OUTPUT_MAX_BYTES = FULL_OUTPUT_MAX_BYTES
M.FULL_OUTPUT_MAX_LINES = FULL_OUTPUT_MAX_LINES
--- Appended where full-mode output passed the ceilings, which callers that
--- promised the whole output report as an error.
M.FULL_LIMIT_NOTE = "[output passed the full-mode limit; redirect it to a file to keep all of it]"
--- Per-tool output limit options. `extend` adds them to a
--- `maki.api.register_options` spec.
M.specs = {
max_output_lines = { type = "integer", desc = "Override `agent.max_output_lines` for this tool." },
max_output_bytes = { type = "integer", desc = "Override `agent.max_output_bytes` for this tool." },
}
function M.extend(spec)
--- Returns max_lines, max_bytes: tool override when set, agent-wide otherwise.
--- Both nil in full mode.
function M.resolve(opts, ctx)
--- opts.max_line_bytes, or 0 (no limit) in full mode.
function M.line_bytes(opts, ctx)
--- Cuts streamed lines the way `cut_middle` cuts a whole text, holding no
--- more than the limits while they arrive. nil limits fall back to the
--- full-mode ceilings, so even full mode stops growing at 64 MiB. Lines go in
--- with `collector:append(line, bytes)` and the text comes out of
--- `collector:result()`.
function M.collector(max_lines, max_bytes)
--- Whether one more line of {bytes} still leaves every line kept, so a
--- caller can save the output elsewhere before the collector drops any.
function Collector:fits(bytes)
--- Adds {line}. {bytes} is its length before a reader cut it, the fourth
--- argument of a `jobstart` line callback, so the marker counts what the cut
--- dropped too. Defaults to `#line`.
function Collector:append(line, bytes)
--- Whether the collector has dropped anything, so a caller that promised
--- the whole output can say it could not keep it.
function Collector:truncated()
--- The newest lines kept with no gap between them, and how many lines came
--- before them: every line until the collector cuts, its tail window after.
function Collector:newest()
function Collector:result()
--- Cuts {text} to the limits keeping its head and its tail, since on a long
--- build or test run the errors and the summary sit at the end. Each end gets
--- half of every limit. A nil limit is unlimited. The marker between the two
--- notes how many lines and bytes it dropped.
function M.cut_middle(text, max_lines, max_bytes)
require("maki.partial")
-- When a tool is cut short, it still hands back what it printed. The marker
-- tells the model that output is real but unfinished. One home for the
-- wording and the painting, so every tool says it the same way.
--- Close {view} on the marker and build the tool reply. {out} is everything
--- the tool streamed, already truncated; empty means the view still shows a
--- placeholder to drop. {reason} is a cancel-hook reason ("cancelled" |
--- "timeout" | "stopped"). {started_at} is the `os.time()` the tool began at.
function M.cut(view, out, reason, timeout_secs, started_at)
require("maki.provider_parse")
-- Typed readers for provider model-list and usage JSON, for use in
-- `list_models` and `fetch_usage` hooks.
--
-- `8192` and `8192.0` both count as whole numbers. A JSON null decodes to nil,
-- and in an array it stops `ipairs`. Numbers above 2^53 come back rounded.
--- A whole, non-negative number up to 2^64, or nil.
function M.as_u64(value)
--- A whole, non-negative number that fits a u32, or nil.
function M.as_u32(value)
--- A number, or nil.
function M.as_f64(value)
--- A boolean, or nil.
function M.as_bool(value)
--- A model row's `pricing`, converted from per-token to per-million-token
--- dollars. Nil unless both `input` and `output` are given, so a partial price
--- never reads as free. A missing cache price is 0.
function M.pricing(input, output, cache_write, cache_read)
--- Maps each `body.data` element through `parse_row`, drops nils, keeps the
--- first row per id, and sorts by id. Returns an empty list when `data` is
--- not an array.
function M.models(body, parse_row)
require("maki.scroll")
-- Relative scrolling on top of maki.fn.winsaveview / winrestview.
-- Positive {delta} scrolls down, negative up. Returns (true, nil) or (nil, err).
local function scroll(delta)
local view, err = maki.fn.winsaveview()
if not view then
return nil, err
end
return maki.fn.winrestview({ topline = view.topline + delta })
end
return scroll
require("maki.shorten_path")
local function normalize_sep(s)
return s:gsub("\\", "/")
end
local function shorten_path(path)
local p = normalize_sep(path)
local cwd = maki.uv.cwd()
if cwd then
cwd = normalize_sep(cwd)
if p:sub(1, #cwd + 1) == cwd .. "/" then
local rel = p:sub(#cwd + 2)
return rel == "" and "." or rel
end
end
local home = maki.uv.os_homedir()
if home then
home = normalize_sep(home)
if p:sub(1, #home + 1) == home .. "/" then
local rel = p:sub(#home + 2)
return rel == "" and "~" or "~/" .. rel
end
end
return path
end
return shorten_path
require("maki.test_helpers")
-- Shared test helpers for Lua plugin specs.
--
-- Provides a lightweight test harness: `case` wraps each block in pcall so a
-- single failure does not abort the rest of the suite. Failures are collected
-- and surfaced by `report()` at the end.
function M.case(name, fn)
function M.eq(actual, expected, msg)
function M.has(s, substr, msg)
function M.mktmpdir(prefix)
function M.rmtree(dir)
function M.report()
require("maki.text_input")
-- TextInput: multi-line editable buffer with a byte-offset cursor.
--
-- Invariants enforced everywhere:
-- * `line` is 1-based and indexes a line that always exists.
-- * `col` is a byte offset inside `lines[line]`, always on a UTF-8 codepoint
-- boundary, so `lines[line]:sub(1, col)` is a complete UTF-8 prefix.
-- * No line ever contains a literal newline; newlines split into rows.
--
-- Parents OWN their keys. `handle_key` returns one of R.IGNORED / R.MOVED /
-- R.CHANGED. Parent dispatchers must filter their own keys (`<Esc>`, `<C-c>`,
-- submit keys, etc.) BEFORE forwarding, because `handle_key` claims any key
-- it can interpret. `<C-a>` is bound to move-home, so a parent that wants it
-- for "select all" must intercept first.
--
-- Keys are in canonical notation, as `win:recv` delivers them. Splitting a
-- line is the `input:split_line()` method rather than a pseudo-key, so every
-- key in KEYMAP is one a terminal can send.
--
-- IGNORED is returned when the buffer literally cannot act (backspace at
-- (1, 0), right at end of buffer, etc.). Parents can use that signal to fall
-- through to their own logic.
--
-- Parity cases live in plugins/lib/tests/spec.lua (TRACE_CASES). Add one
-- whenever you change handle_key semantics.
TextInput.Result = R
function TextInput.new()
function TextInput:value()
function TextInput:is_empty()
function TextInput:line_count()
function TextInput:clear()
-- Returns the codepoint right before the cursor as a string, or nil at the
-- start of a line. Lets callers peek backwards (e.g. "is the previous char
-- a backslash?") without touching internal indices.
function TextInput:char_before_cursor()
function TextInput:insert_text(text)
function TextInput:insert_char(c)
function TextInput:insert_space()
function TextInput:split_line()
function TextInput:remove_char()
function TextInput:delete_char()
function TextInput:remove_word_before()
function TextInput:delete_word_after()
function TextInput:kill_to_end_of_line()
function TextInput:move_left()
function TextInput:move_right()
function TextInput:move_up()
function TextInput:move_down()
function TextInput:move_home()
function TextInput:move_end()
function TextInput:move_word_left()
function TextInput:move_word_right()
function TextInput:handle_key(key)
-- Wrap lines to {width} with {prefix} before the first row. Returns
-- { lines = styled lines, cursor_row = 1-based row holding the cursor }.
function TextInput:render(prefix, prefix_width, width)
require("maki.toast")
-- Corner toast notifications built on floating windows. `maki.ui.flash` gives
-- you one line in the status area. A toast stays up long enough to read, can
-- carry a title, and stacks under the toasts already on screen.
-- Show {text} as a toast, up to 5 lines of it. {opts}: title (string),
-- timeout_secs (integer, default 4). Returns right away and the toast
-- dismisses itself when the time is up.
function Toast.show(text, opts)
require("maki.tool_view")
-- The shared truncate/expand body that tool plugins render through.
--
-- Click handlers get `ev.row`, a 1-based line in this buf; 0 means the
-- click landed outside it (the header). The handler lives on the buf
-- itself, so any wrapper of the same buf (a batch child's foreign handle)
-- reaches the same toggle. Expansion is never stored: the UI records
-- clicked rows and replays them through `restore` in order, so `toggle`
-- stays a pure flag flip + re-render, deterministic across replays.
-- Async highlighting goes through `maki.async.run`; during restore the
-- runtime runs those tasks inline before snapshotting.
-- Right aligned, so the content column stays put when a number gains a digit.
-- Formats the number alone, callers add their own separator.
function ToolView.line_nr_fmt(max_line_nr)
-- opts: max_lines (default 80) shown while collapsed, keep "head"|"tail"
-- (default "tail"), max_expand_lines (default 2000) kept for expansion,
-- max_line_bytes (optional) per-line byte cap. Lines are stored already cut,
-- so a run of huge lines costs no more than short ones while kept for expansion.
-- With max_lines 0 only the set_header lines show until a click expands the
-- view. The UI puts the line count in the tool header, so the row still says
-- how much is hidden.
function ToolView.new(buf, opts)
function ToolView:set_header(lines)
function ToolView:clear()
function ToolView:append(line)
function ToolView:append_text(text)
-- Append {content} with line numbers, then syntax-highlight it for {ext}
-- asynchronously. Returns false when {content} is empty.
function ToolView:set_highlight(content: string, ext)
-- Content rows on screen, for callers with their own per-row click targets. A
-- single hidden line is drawn as itself instead of a notice, so it counts as
-- content too. Rows line up with `all_lines` under keep = "head"; keep = "tail"
-- prints its notice first and shifts them.
function ToolView:visible_count()
function ToolView:toggle()
function ToolView:flush()
function ToolView:update_line(all_idx, line)
-- Call once after the last append so the collapsed notice renders.
function ToolView:finish()
function ToolView.restore_lines(lines, opts)
-- Rebuild a collapsed view from a tool's saved llm_output, click-to-toggle
-- wired. For `restore` hooks.
function ToolView.restore(output, opts)
-- Same, for tools whose live output goes through markdown (`format =
-- "markdown"`). {opts.width} is the wrap width and defaults to the body
-- column of the current terminal. Errors stay plain, as they do live.
function ToolView.restore_markdown(output, is_error, opts)
require("maki.truncate")
--- require("maki.truncate")(text, max_lines, max_bytes)
--- Cuts {text} to the limits and notes how many bytes it dropped. A nil limit
--- is unlimited.