Lua API
Every module and function of the hob Lua API.
Hob plugins are plain Lua files. Everything a plugin can touch lives under
one global table: hob. This reference documents every module, function,
and method. It is generated straight from the source code by hob-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 (hob.fs, hob.uv,
hob.treesitter, hob.keymap, hob.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 hob with --no-jit: it runs your
Lua on the interpreter with complete debug info instead.
A small plugin looks like this:
hob.api.register_command({
name = "greet",
description = "Say hello from Lua",
handler = function()
hob.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 = hob.fs.read("config.json")
if err then
hob.log.error("read failed: " .. err)
return
endLua 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
hob.api.register_action.
fs_read: reading files, and locating the directories hob 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/hob/init.lua that is ~/.config/hob/plugin.toml):
min_hob_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 = trueThe rules:
- No
plugin.tomlat all: every permission is denied, and hob 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 hob 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_hob_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, Hob 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 |
|---|---|
hob |
The global entry point. |
hob.pack |
Declare global packages and inspect package state. |
hob.api |
Plugin registration. |
hob.plan |
Plan-mode surface for plugins. |
hob.agent |
Subagent primitives for plugins that need to talk to an LLM. |
hob.agent.Session |
A subagent session with its own conversation history. |
hob.async |
Tools for running things concurrently in Lua plugins. |
hob.async.Semaphore |
A counting semaphore for limiting how many tasks run at once. |
hob.async.Permit |
One slot in a semaphore, obtained from Semaphore:acquire(). |
hob.async.Task |
Handle returned by hob.async.spawn. |
hob.base64 |
Base64 encoding and decoding, modelled after vim.base64. |
hob.completion_usage |
Persistent completion frecency shared with command usage history. |
hob.env |
Paths to hob’s own directories (config, state, logs, legacy). |
hob.fn |
Process and environment helpers, modeled after Neovim’s vim.fn job |
hob.fs |
File-system utilities, modelled after vim.fs and vim.uv. |
hob.image |
Small building blocks for working with images: probe metadata, decode |
hob.image.Image |
An image you can inspect, resize, and re-encode. |
hob.interpreter |
Run Python code in a memory-safe, time-limited sandbox. |
hob.json |
JSON encoding, decoding, and schema validation. |
hob.json.SchemaValidator |
A compiled JSON Schema validator. |
hob.keymap |
Key mappings, modeled after vim.keymap. |
hob.log |
Structured logging for plugins. |
hob.model |
The model behind the focused session. |
hob.net |
HTTP and plain TCP for plugins. |
hob.net.Conn |
A TCP connection opened by hob.net.connect. |
hob.provider |
Providers implemented in Lua. |
hob.provider.auth |
Credential storage for the providers this plugin registered. |
hob.session |
Host session primitives. |
hob.Timer |
Handle returned by hob.defer_fn. |
hob.task |
The subagents of the focused session and their transcripts. |
hob.text |
Text utilities: format conversion, UTF-8 decoding and the fuzzy matcher |
hob.treesitter |
Tree-sitter parsing and query API. |
hob.treesitter.language |
Language registry for tree-sitter grammars. |
hob.treesitter.query |
Query compilation and lookup. |
hob.treesitter.Query |
A compiled tree-sitter query. |
hob.treesitter.Tree |
A parsed syntax tree. |
hob.treesitter.Node |
A single node in a parsed syntax tree. |
hob.treesitter.LanguageTree |
Manages parsing of a source string for a single language. |
hob.ui |
Functions for building interactive UI. |
hob.ui.Win |
Handle to a floating or split window. |
hob.ui.Buf |
A content buffer that holds styled lines of text. |
hob.ui.status_bar |
The one-row bar at the bottom of the screen. |
hob.uv |
System and environment utilities, modelled after vim.uv. |
hob.yaml |
YAML encoding and decoding. |
hob
The global entry point. Every API lives under this table.
hob.setup()
hob.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:
hob.setup({
ui = { vim_mode = true },
plugins = { completion = { enabled = true } },
})hob.split()
hob.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 hob. {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:
hob.split("a,b,c", ",") -- { "a", "b", "c" }
hob.split("x*y*z", "*", { plain = true }) -- { "x", "y", "z" }
hob.split("\nhello\nworld\n", "\n", { trimempty = true }) -- { "hello", "world" }hob.packadd()
hob.packadd({name})Load an installed package that is not active.
Parameters:
{name}(string) Package name.
hob.defer_fn()
hob.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
hob.async.sleep loop inside hob.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: (hob.Timer) Handle with :stop() to cancel before it fires.
Example:
-- A toast that dismisses itself 4 seconds later:
local buf = hob.ui.buf({ scratch = true })
buf:line("copied!")
local win = hob.ui.open_win(buf, { split = "right", width = 20, height = 3 })
hob.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 = hob.defer_fn(repaint, 500)
endhob.notify()
hob.notify({msg}, {level?}, {opts?})Show a one line notice. By default it goes to hob.ui.flash, with
{opts.title} in front of the message when you pass one. Without a UI
(hob -p, the sdk, ACP), the notice goes to the log.
There is one handler for the whole process. Once a plugin calls
hob.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:
hob.notify("saved!")
hob.notify("build failed", "error", { title = "make" })hob.set_notify_handler()
hob.set_notify_handler({handler})Install the handler that every hob.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 hob.async.run. If it raises an error, the error is logged
and the notice falls back to hob.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("hob.toast")
hob.set_notify_handler(function(msg, level, opts)
Toast.show(msg, { title = opts and opts.title, level = level })
end)hob.deepcopy()
hob.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
hob. Table keys are copied too. Functions, userdata (including
hob.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 = hob.json.decode('{"files": []}')
local copy = hob.deepcopy(input)
copy.mode = "strict"
print(hob.json.encode(copy)) -- {"files":[],"mode":"strict"}hob.NIL
hob.NILhob.NIL is a value that stands for JSON null, like vim.NIL. hob.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 == hob.NIL for null. Tool handler arguments and event payloads use nil for null instead, never hob.NIL.
Example:
local t = hob.json.decode('{"a": null}')
assert(t.a == hob.NIL)
print(hob.json.encode(t)) -- {"a":null}hob.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.
hob.pack.add()
hob.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:
hob.pack.add({
{ src = "https://github.com/user/hob-goal", version = "main" },
})hob.pack.get()
hob.pack.get({names?}, {opts?})Get package state without changing the installed set.
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.
hob.api
Plugin registration. This is where you tell hob 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).
hob.api.register_tool({ name = "greet", ... })
hob.api.register_prompt_hint({ slot = "tool_usage", content = "..." })hob.api.register_tool()
hob.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(hob.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) 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. A tool declaring neither costs those plugins every permission.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. The field reaches the header, the permission rules and the handler as an absolute path, resolved once against the process folder when the call is parsed.start_annotation(string|table) Schema field used to annotate the start header with a count (string) or timeout ({ field, kind="timeout" }).untracked_writes(boolean) The tool can write files its input does not name, as a shell does. When hob works in a Git checkout, the dispatcher then compares that checkout before and after each call and records what changed for the review; a code rewind puts it back only withagent.rewind_shell_changeson, since what changed is inferred from Git. Files Git ignores and files outside that checkout are not tracked, and outside Git nothing is. Only what the call writes before it moves to the background is tracked, and only where hob can tell what a file held before and that the call’s run wrote it; anything else counts as a change from outside. Default: false.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:
hob.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,
})hob.api.register_permission_rule()
hob.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:
hob.api.register_permission_rule({
tool = "write",
scope = notes_dir .. "/**",
})hob.api.register_command()
hob.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. Enter andhob.ui.input_submitcomplete the selected command instead of running it while required arguments are missing, unless completion would leave the input unchanged. In that case the handler runs to show usage. Directhob.api.run_commandcalls still reach the handler with emptyopts.args, so validate required arguments there too.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:
hob.api.register_command({
name = "/hello",
description = "Say hello",
handler = function()
hob.ui.flash("Hello from my plugin!")
end,
})hob.api.register_prompt_hint()
hob.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.
Parameters:
{spec}(table) Hint specification:slot(string) Required. Aggregate slot name (e.g. “tool_usage”, “conventions”).content(string|function) Required. Static text, or afunction()that returns a string. Max 1 MiB.prompt(string|string[]) Optional. Restrict to specific prompt ids (e.g. “system”).
Example:
hob.api.register_prompt_hint({
slot = "tool_usage",
content = "- Prefer **grep** over reading entire files.",
})hob.api.register_options()
hob.api.register_options({spec})Declare the options your plugin accepts under plugins.<name> in
hob.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 = hob.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." },
})hob.api.set_prompt()
hob.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. 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:
hob.api.set_prompt({
prompt = "system",
slot = "conventions",
content = "State uncertainty and cite your evidence.",
})
hob.api.set_prompt({
prompt = "system",
content = "You help analyse information.\n{{tool_usage}}",
})hob.api.get_tools()
hob.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).
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?, enabled }.
Example:
local tools = hob.api.get_tools()
for _, t in ipairs(tools) do
print(t.name, t.enabled)
endhob.api.get_tool()
hob.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.
Parameters:
{name}(string) Exact tool name.
Returns: (table|nil) Tool entry with fields { name, schema, audiences, kind?, background_params?, header?, restore?, format? }, or nil if not found.
Example:
local t = hob.api.get_tool("bash")
if t then
print("bash audiences:", table.concat(t.audiences, ", "))
endhob.api.run_command()
hob.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 hob.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:
-- /history as an alias for the built-in session picker:
hob.api.register_command({
name = "/history",
description = "Alias for /resume",
handler = function()
local ok, err = hob.api.run_command("/resume")
if not ok then
hob.ui.flash("could not run /resume: " .. err)
end
end,
})hob.api.create_autocmd()
hob.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: "UserPrompt", "TurnStart", "TurnEnd",
"TurnError", "ToolStart", "ToolDone", "AutoCompacting",
"CompactionDone", "PlanReady", "SessionReset", "SessionDeleted", "SessionEnd",
"SessionFocusChanged", "SessionStatusChanged", "SessionTitleChanged",
"SessionCwdChanged", "TaskStatusChanged", "TaskStopped", "TaskFocusChanged",
"ModelChanged", "ProviderUsageChanged", "InputChanged", "ModeChanged" and
"FileIndexReady". Plugins can also fire their own events with exec_autocmds.
Every host event carries data.session_id except "FileIndexReady"
(directory-scoped), "ProviderUsageChanged" (provider-scoped) and
"ModeChanged", since the mode is the same in every session. For
"SessionReset" and "SessionEnd" that is the session being left behind;
"SessionDeleted" names the session whose stored history was deleted.
Other session events name the session they describe, which need not be
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 run. It does not repeat for queued prompts consumed during that run."UserPrompt":data.text, the original user prompt, before anyagent.user_messagerewrite or refusal. In the TUI it fires once on immediate submission, or once per queued prompt when consumed (including restored prompts), even when several prompts share a model turn. Merely queueing or removing a prompt, manual compaction, context injections, and subagent prompts do not fire it. The prompt that autoreview sends to repair its findings or a failed check fires it too, withdata.autoreview = true. Every other prompt hasdata.autoreview = false."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."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_idtohob.plan.read."SessionDeleted": onlydata.session_id, after successful storage deletion throughhob.session.delete, for a live or stored session. Failed deletions stay quiet; deleting an already absent session succeeds."SessionFocusChanged":data.previous_session_id, absent on the first focus at startup."SessionStatusChanged":data.status("working","needs_input", or"idle"),data.title,data.focused, anddata.paused(booleans). Also fires when pause changes without changing status. A session stays"working"while a background task it waits on still runs."SessionTitleChanged":data.title,data.title_ownership("unknown","automatic", or"manual"),data.title_revision, anddata.focused(boolean), when the title or its ownership changes."SessionCwdChanged":data.cwd, the session’s new working directory, when/cdchanges it. Every tab shares that one directory. A/cdthat lands where hob already is stays quiet."TaskStatusChanged":data.id,data.name,data.status("working","idle","done","error", or"cancelled"), anddata.subagent(boolean), when a non-main chat starts or changes status. This includes moved tool calls and their reported parts, not just subagents.data.subagentis always present: true for chats backed by an agent session (including nested and finished agents), false otherwise. A chat classified as a subagent later fires again even if its status is unchanged. A task a plugin opened withhob.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 throughhob.task.stop. A plugin task carriesdata.plugin, and by then it is already gone fromhob.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 non-main chat’s id, whatctx:task_id()reports inside a tool). Fires for the chat cycling keys,hob.task.focus, and a session switch that lands on another task."ModelChanged":data.modelin the shapehob.model.getreturns, plusdata.previous_spec. Fires when the model, the thinking level, fast mode or the account changes, whatever changed it. The account counts as changed when its label or kind does, such as an account that resolves again after a new login.data.previous_specequal todata.model.specmeans only the thinking level, fast mode or the account moved. Picking the setup already in use stays quiet, and so does startup. A restored session holds its thinking level or fast mode until the model list loads, and fires the event when that value takes effect."ProviderUsageChanged": TUI-only, withev.datashaped as{provider, account?, usage?, error?}and nosession_id.provideris the slug,accountthe label of the account the quota belongs to for a provider that keeps several,usagehas the shapehob.model.usagereturns, anderroris a request failure. Unsupported providers have nilusageand nilerror. Fires only when the result changes. The initial success, error, or unsupported result counts as a change, and repeated equal results stay quiet. The result is published to the shared cache before delivery. Callhob.model.usageinitially and on model or focus changes, then handle this event for updates without polling."InputChanged":data.text,data.cursor,data.anchor,data.version,data.vim_modeanddata.session_id, ashob.ui.inputreports them. A change of vim mode alone fires nothing.data.cursor_onlyis true when only the cursor or the selection moved.data.sourcenames the plugin whosehob.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 callhob.ui.input_decoratewithout looping."ModeChanged":data.old_modeanddata.new_mode, each"n"or"i". Fires wheneverhob.fn.mode()changes: onhob.ui.set_mode, when vim mode switches between normal and insert, 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, whateverhob.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:
"UserPrompt" and "TurnStart" without data.text, "ToolDone" without
data.input, "CompactionDone" without data.summary, and "InputChanged"
without data.text. Hob warns once per plugin and event, naming what was
left out. Set metadata_only = true to receive only metadata without a
warning, even when the plugin holds session_read. Events a plugin fires
under its own names arrive as fired.
"TurnEnd" fires once per turn and only for the main session, so
subagent turns never show up. A turn stopped with Esc or Ctrl+C fires it
with reason = "cancelled" once the run has stopped. A manual /compact
ends its run without ending a turn, so it stays quiet too.
"ToolStart", "ToolDone", "AutoCompacting", "CompactionDone",
"TurnEnd", and "TurnError" also fire under hob -p and sdk mode.
"SessionEnd" comes from every driver, and "FileIndexReady" from the
shared file index. All other host events come from hob-ui only, including
"UserPrompt", "TurnStart", and the other session events. hob-acp runs
the agent on its own loop and does not call the dispatcher yet, so plugins
loaded under ACP receive no turn events.
"SessionEnd" is the teardown signal, not proof of storage deletion;
use "SessionDeleted" for that. 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 (hob.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 hob.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).metadata_only(boolean) omit host event content without warning (default false).pattern(string|string[]) only fire when the pattern matches."*"matches everything. Omit to match all.
Returns: (integer) Autocmd id.
Example:
local id = hob.api.create_autocmd("TurnEnd", {
callback = function(ev)
print("turn ended: " .. ev.event)
end,
})hob.api.del_autocmd()
hob.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:
hob.api.del_autocmd(id)hob.api.exec_autocmds()
hob.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:
hob.api.exec_autocmds("MyEvent", {
pattern = "init",
data = { msg = "hello" },
})hob.api.register_action()
hob.api.register_action({name}, {callback}, {opts?})Registers {callback} as an action that hob.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
hob.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 hob.ui.action, like "completion.accept".
Example:
-- Writes a file path into the input, so a caller must hold what that takes:
hob.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" } })hob.api.declare_slot()
hob.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 hob runs.
The chain is async: the default and every layer may park (hob.fs.*,
hob.fn.jobwait, hob.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 = hob.api.declare_slot("myplugin.render", function(text)
return text:upper()
end, { capability = {} })
print(render("hello")) -- HELLOhob.api.set_slot()
hob.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.
Hob 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 hob.plan.
Hob 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. An agent.user_message replacement may include
context = { { text = "model context", display = "optional notice" } }.
Nonblank string text entries attach as observations after the input’s
preamble and before its accepted prompt. display is optional and supplies
a notice line; without it the context is model-only. The observations are
marked prompt_context so rewind and fork remove them with their prompt.
Notices follow their attached prompt, live and on restore.
Context alone leaves the prompt unchanged, and dropped messages attach no context.
Wrapping one costs every permission. 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. req.input is the input the call runs with, the path it writes
already resolved, and req.scopes are what the rules judged. 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:
hob.api.set_slot("myplugin.render", function(prev, text)
return prev("[" .. text .. "]")
end)hob.api.get_slots()
hob.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(hob.api.get_slots()) do
print(name, info.owner, info.declared)
endhob.plan
Plan-mode surface for plugins.
Read the plan, and shape the plan form by layering the two slots hob
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:
hob.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)
hob.fn.system({ "git", "commit", "-am", "plan" })
hob.session.set_mode("build", { session = opts.session })
hob.session.prompt("Implement " .. opts.path, { session = opts.session })
end,
})
return rows
end)
-- Render the plan yourself for as long as this plugin is loaded:
hob.api.set_slot("ui.plan_form", function(prev, ev)
local plan = hob.plan.read({ session = ev.session })
return false
end)hob.plan.read()
hob.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 = hob.plan.read({ session = id })
if plan and plan.ready then
print(plan.path, plan.content)
endhob.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 = hob.agent.tools(ctx, { audience = "general_sub" })
local sess = hob.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] = hob.async.spawn(function()
while true do
hob.async.sleep(5 * 60 * 1000)
-- Prompts are denied here, so this needs an allow rule like `gh run list *`.
local sess = hob.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 = (hob.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
hob.session.notify("[ci-monitor] " .. text, { session = sid, wake = true })
end
end
end
end)
end
hob.api.create_autocmd("SessionFocusChanged", {
callback = function(ev) start(ev.data.session_id) end,
})
hob.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,
})hob.agent.resolve_model()
hob.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 byhob.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 = hob.agent.resolve_model(ctx, { tier = "fast" })
if err then error(err) end
print(model.spec, model.tier)hob.agent.system_prompt()
hob.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 byhob.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 = hob.agent.system_prompt(ctx, {
prompt_id = "research",
instructions = true,
tools = tool_defs,
})
if err then error(err) endhob.agent.tools()
hob.agent.tools({ctx}, {opts?})Get the list of tool definitions for a given audience. Pass the result
straight into hob.agent.session() or use it to inspect what tools are
available.
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 tohob.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 = hob.agent.tools(ctx, {
audience = "general_sub",
except = { "bash", "write" },
})
if err then error(err) end
print(#defs .. " tools available")hob.agent.callable_tools()
hob.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. hob.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 = hob.agent.callable_tools(ctx)
if err then error(err) end
for _, t in ipairs(tools) do
print(t.source, t.alias or t.name)
endhob.agent.call_tool()
hob.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?) Tool output text, 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 = hob.agent.call_tool(ctx, "bash", {
command = "ls -la",
timeout = 10,
})
if err then error(err) end
print(out)hob.agent.session()
hob.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, hob.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 hob.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. A prompt
is no gate under YOLO or an allow rule, and a background session has
nobody to prompt. A tool declaring a permission (bash with run, read
with fs_read) costs that one. A tool declaring none (batch,
code_execution), or mcp = true on a chat with MCP servers, costs every
permission except agent. local_tools cost nothing, they run as the
plugin. The bundled task 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 hob.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 hob.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 hob.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 hob -p and ACP there is no live chat
session, so opening one fails with “session not live”. The
hob.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 (fromhob.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 wayhob.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 = hob.agent.tools(ctx, { audience = "general_sub" })
local sess, err = hob.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) endhob.agent.complete()
hob.agent.complete({opts})Make one isolated model request, with no tools, history, task tab or changes
to the chat’s context. Usage is billed to the named live chat session even
if the response is rejected. There are no retries. The calling task, chat
session ending, plugin unloading or timeout cancels the request. Run in an
async task or autocmd callback. Backends known not to enforce output limits
(including OpenAI Coding Plan) are rejected before sending a request, even
when max_tokens is left at its default.
Requires the agent plugin permission.
Parameters:
-
{opts}(table) Required fields:session(string) id of the live chat session to bill.model_spec(string) model spec string to use.system(string) system prompt.prompt(string) user prompt.
Optional fields:
max_tokens(integer?) output limit, 1..4096. Default: 384.timeout(number?) deadline in seconds, greater than 0 and at most 120. Default: 90.
Returns: (table?, string?) { text, usage, cost? }, or (nil, err). Truncated
responses and tool calls are errors. Thinking is off where the model
permits it; fast mode is off.
hob.agent.list()
hob.agent.list({opts})List the sessions plugins opened on a chat session without a ctx, see
hob.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, including descendant sessions, updated after each turn. nil until a priced turn ends. In contrast,hob.task.list().costcovers only that task’s own model turns.
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(hob.agent.list({ session = id })) do
print(s.plugin, s.name, s.status, os.time() - s.started_at)
endhob.agent.Session
A subagent session with its own conversation history.
Create one with hob.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 hob.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()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.
Session:id()
Session:id()The task id of this session. A session opened by chat session id goes by
this id in hob.task.list() and the "TaskStopped" event, so a plugin
can tell which of those are its own.
Returns: (string) Session task id.
hob.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 = hob.async.gather({
function() return fetch("a.txt") end,
function() return fetch("b.txt") end,
})hob.async.run()
hob.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 hob.async.spawn.
Parameters:
{fn}(function) Zero-argument function to execute.{on_finish?}(function?) Optional callbackfunction(err, result). Called once {fn} completes.
Example:
hob.async.run(function()
local data = expensive_fetch()
process(data)
end)hob.async.spawn()
hob.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 hob alive: hob -p drops it on exit.
Code that runs 5 seconds without yielding is still stopped. See
hob.async.sleep.
Parameters:
{fn}(function) Zero-argument function to run.
Returns: (hob.async.Task) Handle with :cancel().
Example:
local task = hob.async.spawn(function()
while true do
hob.async.sleep(2000)
report()
end
end)
task:cancel()hob.async.sleep()
hob.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 hob.async.spawn. For a
one-shot timer that outlives the tool call, such as a toast that
dismisses itself, use hob.defer_fn.
Parameters:
{ms}(integer) Milliseconds to wait. Negative values raise an error.
Example:
hob.async.spawn(function()
while true do
poll()
hob.async.sleep(5000)
end
end)
-- A long loop that keeps the rest of hob responsive:
for i, line in ipairs(lines) do
if i % 1000 == 0 then
hob.async.sleep(0)
end
process(line)
endhob.async.await()
hob.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 = hob.async.await(2, http.get, url)hob.async.wrap()
hob.async.wrap({argc}, {fn})Create a coroutine-friendly wrapper around a callback-based function. The wrapper calls hob.async.await for you, so you can use the result like a normal function call.
Parameters:
{argc}(integer) Callback position, forwarded tohob.async.await.{fn}(function) Callback-based function to wrap.
Returns: (function) Wrapped function you can call like a normal function.
Example:
local get = hob.async.wrap(2, http.get)
local body = get(url)hob.async.join()
hob.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:
hob.async.join(4, {
function() process(files[1]) end,
function() process(files[2]) end,
function() process(files[3]) end,
})hob.async.gather()
hob.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 = hob.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
endhob.async.semaphore()
hob.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: (hob.async.Semaphore) A new semaphore.
Example:
local sem = hob.async.semaphore(5)
-- each task acquires a permit before doing work
local permit = sem:acquire()
do_work()
permit:release()hob.async.on_cancel()
hob.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:
hob.async.on_cancel(function(reason)
view:append({ { reason, "tool_error" } })
ctx:finish({ llm_output = partial .. "\n[cancelled; output is partial]", is_error = true })
end)
hob.async.gather(children)hob.async.Semaphore
A counting semaphore for limiting how many tasks run at once.
Create one with hob.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: (hob.async.Permit) A permit handle. Call :release() when done, or let it be garbage collected.
Example:
local sem = hob.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: (hob.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()
endhob.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.
hob.async.Task
Handle returned by hob.async.spawn.
Task:cancel()
Task:cancel()Stop the task. A task that is waiting ends right away and runs its
hob.async.on_cancel hooks. A task that cancels itself stops at its
next yield. Extra calls do nothing.
hob.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 hob.fs.read_bytes.
local encoded = hob.base64.encode("hello")
local decoded = hob.base64.decode(encoded)hob.base64.encode()
hob.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:
hob.base64.encode("hello") -- "aGVsbG8="hob.base64.decode()
hob.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:
hob.base64.decode("aGVsbG8=") -- "hello"hob.completion_usage
Persistent completion frecency shared with command usage history. Usage is global by full name across repositories. Reads and writes run off the Lua thread and return error pairs on storage failure. Permission denials raise, as with other filesystem APIs.
hob.completion_usage.scores()
hob.completion_usage.scores({names})Read normalized frecency scores for the supplied full completion names.
Scores range from 0 (unused) toward 1, combining frequency with time decay.
Names are used unchanged: pass "$skill" for a skill, distinct from the
"/skill" command in the shared command usage history. Usage is global by
full name across repositories. Only requested names are returned, including
unused names with score 0.
Requires the fs_read plugin permission.
Parameters:
{names}(table) Array of full completion name strings to look up.
Returns: (table|nil, string|nil) Scores keyed by full name, or nil and a storage error.
Example:
local scores, err = hob.completion_usage.scores({ "$review", "$test" })
if err then hob.log.warn(err) endhob.completion_usage.record()
hob.completion_usage.record({names})Persist one use of each full completion name in a single storage update.
Pass "$skill" for skills so they do not collide with "/" commands.
Usage is global by full name across repositories, preserving other entries.
An empty batch succeeds without accessing storage. The call yields while
storage is updated; storage failures return an error pair so the caller can
continue without persisting usage.
Requires the fs_write plugin permission.
Parameters:
{names}(table) Array of full completion name strings, including prefixes.
Returns: (true|nil, string|nil) True on success, or nil and a storage error.
Example:
local ok, err = hob.completion_usage.record({ "$review", "$test" })
if err then hob.log.warn(err) endhob.env
Paths to hob’s own directories (config, state, logs, legacy).
Use these to locate config files or persistent state without hard-coding paths.
These answer where hob 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
(hob.uv.os_getenv), where secrets live.
local cfg = hob.env.config_dir()hob.env.state_dir()
hob.env.state_dir()Return the directory where hob stores runtime state (sessions, auth tokens, etc.).
Typically something like ~/.local/state/hob.
Requires the fs_read plugin permission.
Returns: (string?) State directory path, or nil if it cannot be determined.
Example:
local dir = hob.env.state_dir()hob.env.config_dir()
hob.env.config_dir()Return the directory where hob looks for user configuration files.
Typically something like ~/.config/hob.
Requires the fs_read plugin permission.
Returns: (string?) Config directory path, or nil if it cannot be determined.
Example:
local dir = hob.env.config_dir()hob.env.logs_dir()
hob.env.logs_dir()Return the directory where hob writes its log files (hob.log).
Typically something like ~/.local/logs/hob.
Requires the fs_read plugin permission.
Returns: (string?) Logs directory path, or nil if it cannot be determined.
Example:
local dir = hob.env.logs_dir()hob.env.legacy_dir()
hob.env.legacy_dir()Return the legacy config path (~/.hob), 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.
hob.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 = hob.fn.jobstart("git status", {
on_exit = function(_, code) print("done: " .. code) end,
})hob.fn.jobstart()
hob.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 hob. 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 hob 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 and0: 64 MiB, thehob.fsread limit).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 = hob.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
hob.log.warn("rg failed to start: " .. err)
endhob.fn.jobstop()
hob.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:
hob.fn.jobstop(id)hob.fn.jobforget()
hob.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:
hob.fn.jobforget(id)hob.fn.jobwait()
hob.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 = hob.fn.jobstart("echo hello")
local result, err = hob.fn.jobwait(id, 5000)
if result then
print(result.stdout)
endhob.fn.jobinfo()
hob.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 = hob.fn.jobinfo(id)hob.fn.joblist()
hob.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 = hob.fn.joblist(hob.session.current())hob.fn.jobattach()
hob.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 = hob.session.current()
local id = hob.fn.jobfind("log-tail")
or hob.fn.jobstart({ "tail", "-F", path }, {
name = "log-tail",
scope = { session = sid },
})
hob.fn.jobattach(id, {
on_stdout = function(_, line) hob.session.notify(line, { session = sid }) end,
on_exit = function(_, code) hob.session.notify("tail died: " .. code, { session = sid }) end,
})hob.fn.jobfind()
hob.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 = hob.fn.jobfind("log-tail")
if not id then
id = hob.fn.jobstart("tail -F /tmp/log", { name = "log-tail", scope = "plugin" })
endhob.fn.executable()
hob.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 hob.fn.executable("rg") == 1 then
-- use ripgrep
endhob.fn.winsaveview()
hob.fn.winsaveview()Read the viewport of the focused chat transcript, like Neovim’s
vim.fn.winsaveview(). The transcript is the only scrollable window
hob 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 = hob.fn.winsaveview()
hob.fn.winrestview({ topline = view.topline + 1 })hob.fn.winrestview()
hob.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:
hob.fn.winrestview({ topline = 1 })hob.fn.mode()
hob.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:
hob.keymap.set({ "n", "i" }, "<M-m>", function()
hob.ui.set_mode(hob.fn.mode() == "n" and "i" or "n")
end)hob.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 = hob.fs.read("init.lua")
if err then return endhob.fs.read()
hob.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 = hob.fs.read("config.toml")
if err then
hob.log.warn("could not read config: " .. err)
return
end
local tail = hob.fs.read("server.log", { offset = -50 })hob.fs.read_bytes()
hob.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 hob.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 = hob.fs.read_bytes("image.png")
if err then return end
local encoded = hob.base64.encode(buf)
local header = hob.fs.read_bytes("image.png", { len = 8 })hob.fs.read_lines()
hob.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 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 = hob.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))hob.fs.metadata()
hob.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 = hob.fs.metadata("src/main.rs")
if meta and meta.is_file then
print("size: " .. meta.size)
endhob.fs.dirname()
hob.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:
hob.fs.dirname("/home/user/init.lua") -- "/home/user"hob.fs.basename()
hob.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:
hob.fs.basename("/home/user/init.lua") -- "init.lua"hob.fs.joinpath()
hob.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:
hob.fs.joinpath("src", "api", "fs.rs") -- "src/api/fs.rs"hob.fs.normalize()
hob.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:
hob.fs.normalize("src/../src/api") -- "/home/user/project/src/api"hob.fs.abspath()
hob.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:
hob.fs.abspath("src/main.rs") -- "/home/user/project/src/main.rs"hob.fs.parents()
hob.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 = hob.fs.parents("/home/user/project/src")
-- { "/home/user/project", "/home/user", "/home", "/" }hob.fs.root()
hob.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 = hob.fs.root("src/main.rs", { ".git", "Cargo.toml" })
if root then print("project root: " .. root) endhob.fs.relpath()
hob.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:
hob.fs.relpath("/home/user", "/home/user/project/src") -- "project/src"hob.fs.ext()
hob.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:
hob.fs.ext("main.rs") -- "rs"
hob.fs.ext("Makefile") -- nilhob.fs.dir()
hob.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.
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 = hob.fs.dir("src", { depth = 2 })
if err then return end
for _, e in ipairs(entries) do
print(e[1], e[2]) -- "main.rs" "file"
endhob.fs.write()
hob.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 = hob.fs.write("out.txt", "hello world")
if err then print("write failed: " .. err) endhob.fs.append()
hob.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 = hob.fs.append("out.log", "line\n")
if err then print("append failed: " .. err) endhob.fs.atomic_write()
hob.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 = hob.fs.atomic_write("state.json", encoded)
if err then print("atomic write failed: " .. err) endhob.fs.atomic_create()
hob.fs.atomic_create({path}, {content})Atomically create {path} with {content}, failing if a file, symlink, or directory already exists there. The parent directory must exist. Readers observe only the complete new file. 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 = hob.fs.atomic_create("export.json", encoded)
if err then print("atomic create failed: " .. err) endhob.fs.rename()
hob.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 = hob.fs.rename("out.log", "out.log.1")
if err then print("rename failed: " .. err) endhob.fs.rm()
hob.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 = hob.fs.rm("temp.txt")
if err then print("rm failed: " .. err) end
hob.fs.rm("stale_dir", { recursive = true, force = true })hob.fs.mkdir()
hob.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:
hob.fs.mkdir("a/b/c", { parents = true })hob.fs.glob()
hob.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.
hob.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 = hob.fs.glob("**/*.lua", { path = "plugins", limit = 10 })
if err then return end
for _, f in ipairs(files) do print(f) endhob.fs.grep()
hob.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 = hob.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
endhob.fs.fuzzy_files()
hob.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 hob.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.
The query reads like fzf’s: spaces separate terms that all have to match,
and a term can be 'exact, ^prefix, suffix$ or !not, with smart
case. A | standing alone between two terms matches either of them, so
src | lib main needs src or lib, and main. \| is a literal |.
The Ctrl+S picker has no |, so a query that uses one ranks differently there.
complete is false while a walk is filling the list, so an empty items
means “not found yet” and asking again is worth it. hob 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 hob.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 hob 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.literal(boolean) disable query-operator parsing, treating operators as ordinary characters. Still uses fuzzy matching with space-separated terms, not exact matching of the entire string. Default false.
Returns: (table?, string?) { root = string, complete = boolean, crashed = boolean, truncated = boolean, items = { { path = string, score = integer, 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. score is what the query scored the path at, higher is better and 0 for an empty query, so a plugin can rank its own rows against these. 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 = hob.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") endhob.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 = hob.image.decode(raw_bytes)
local small = img:resize(1024, 768)
local png = small:encode("png")hob.image.probe()
hob.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 = hob.image.probe(raw_bytes)
if err then error(err) end
print(info.format, info.width, info.height)hob.image.decode()
hob.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: (hob.image.Image?, string?) Decoded image, or (nil, err) on failure.
Example:
local img, err = hob.image.decode(raw_bytes)
if err then error(err) end
print(img:width() .. "x" .. img:height())hob.image.Image
An image you can inspect, resize, and re-encode.
Get one from hob.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 hob.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: (hob.image.Image) A new image handle (or the same one if no resize was needed).
Example:
local img = hob.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 datahob.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 = hob.interpreter.run("print('hello')", {
timeout = 10,
max_memory_mb = 128,
on_output = function(line) print(line) end,
})hob.interpreter.run()
hob.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.
A cancel answers (nil, "cancelled") once the tool or file callback
already running returns, and no callback starts after it.
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 = hob.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) endhob.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 = hob.json.encode({ ok = true })
local t = hob.json.decode(s)hob.json.encode()
hob.json.encode({value})Turn a Lua value into a JSON string. Tables, strings, numbers,
booleans, nil, and hob.NIL (which becomes null) all work. A
hob.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 (hob.json.decode,
hob.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 = hob.json.encode({ name = "hob", version = 1 })
print(s) -- {"name":"hob","version":1}hob.json.decode()
hob.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 hob.NIL, so
a key holding null is still there and encoding the result gives the same
JSON back. hob.NIL is a special value that stands for JSON null. It is
truthy, so test for null with x == hob.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 hob.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 = hob.json.decode('{"x": 42, "y": null}')
print(t.x) -- 42
print(t.y == hob.NIL) -- true
local u = hob.json.decode('{"y": null}', { luanil = { object = true } })
print(u.y) -- nilhob.json.schema_validator()
hob.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: (hob.json.SchemaValidator?, string?) Validator, or nil plus an error.
Example:
local v, err = hob.json.schema_validator({
type = "object",
properties = { name = { type = "string" } },
required = { "name" },
})
local errs = v:validate({ name = "hob" })
assert(errs == nil)hob.json.SchemaValidator
A compiled JSON Schema validator. Create one with hob.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
endhob.keymap
Key mappings, modeled after vim.keymap.
hob.keymap.set({ "n", "i" }, "<C-t>", function()
print("hello")
end, { desc = "Say hello" })Modes
As in Neovim, hob 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 hob.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 hob.fn.mode(), and watch it
with the "ModeChanged" autocmd.
-- A tiny vim mode: Esc leaves insert mode, i goes back.
hob.keymap.set("i", "<Esc>", function() hob.ui.set_mode("n") end)
hob.keymap.set("n", "i", function() hob.ui.set_mode("i") end)
-- dd deletes the cursor's line. A lone d expires after 500 ms.
local pending
hob.keymap.set("n", "d", function(ev)
if not pending then
pending = hob.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")
hob.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.
With the built-in vim mode on (ui.vim_mode), vim’s normal mode is
"n" and its insert mode is "i", and vim’s own commands, like x or
dd, still edit the input in normal mode. While a vim command is half
typed, keys without a modifier go to vim, so d and then a bound key
still reach vim. A key with a modifier, other than <C-r>, cancels the
command and goes to its binding. <Esc> stays with vim while it leaves
insert mode or cancels a command.
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.- Hob’s modals and prompts, then the focused window, then Hob’s
pickers, then the focused image chips of the chat input. They take
every key, except the plan form, the
/command list and the image chips, which pass on the keys they do not use. The image chips first give the keyboard back to the text, so the key goes on as if they had never been focused. 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 ofhob.ui.open_win. <Esc>while the agent runs, in either mode. Hob takes it, and a second one in a row cancels the turn.- Global bindings, the last
setfirst. - Hob’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 hob.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() endA 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 hob 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.
hob.keymap.set()
hob.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 hob 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, hob 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
hob.ui.input_submit.
Throws on an invalid mode or key, on <C-c>, <C-z>, <C-\>, <C-4>,
\ and <M-\>, which stay reserved for quit, suspend, the LazyGit toggle
and literal backslash insertion, even for trusted plugins, 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, ashob.ui.inputreturns it. Pass itsversionandsession_idtohob.ui.input_edit. Only withsession_read, else nil.text(string?)<Paste>only: the pasted text, with\nline endings. hob does not insert it. It is cleaned the wayhob.ui.input_editcleans text, so#ev.textis what inserting it adds. Only withsession_read, else nil.fallback(function) runs hob’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
hob.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/?.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:
hob.keymap.set("i", "<Tab>", function(ev)
local st = ev.input
if st.text ~= "" then
return ev.fallback()
end
hob.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 = hob.ui.buf()
local win = hob.ui.open_win(buf, { focus = false, width = 20, height = 3 })
hob.keymap.set("i", "<Esc>", function()
hob.keymap.del("i", "<Esc>", { buffer = buf })
win:close()
end, { buffer = buf })hob.keymap.del()
hob.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 hob’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:
hob.keymap.del({ "n", "i" }, "<C-t>")hob.keymap.normalize()
hob.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 = hob.keymap.normalize("<Enter>") -- "<CR>"hob.log
Structured logging for plugins.
Each call emits a tracing event tagged with the calling plugin’s name.
Messages show up in hob’s log output, which you can view with hob --log.
hob.log.info("ready")
hob.log.warn("something looks off")hob.log.debug()
hob.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:
hob.log.debug("loaded " .. #items .. " items")hob.log.info()
hob.log.info({msg})Emit an INFO-level log message. Good for normal operational events.
Parameters:
{msg}(string) Message to log.
Example:
hob.log.info("plugin initialized")hob.log.warn()
hob.log.warn({msg})Emit a WARN-level log message. Use for recoverable problems.
Parameters:
{msg}(string) Message to log.
Example:
hob.log.warn("config file missing, using defaults")hob.log.error()
hob.log.error({msg})Emit an ERROR-level log message. Use for failures that need attention.
Parameters:
{msg}(string) Message to log.
Example:
hob.log.error("failed to connect to API")hob.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. Focused-session operations require an interactive UI. Model info, tier resolution, and explicit cached account quota reads also work without one.
hob.model.get()
hob.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.
account names the credentials the session sends, for a provider that
keeps several accounts (OpenAI), and is nil otherwise: {id?, label, kind}. label is what the status bar shows: the email when there is one,
with the end of the id added when two accounts share it. A saved key with
no email shows only its first and last four characters. kind is
"subscription", "api_key", "environment", or "unavailable" while
the session’s own account does not resolve. id is the saved account’s
local id, nil for the environment key.
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, account?, thinking, thinking_shown, thinking_options, fast, supports_thinking, supports_fast}, or nil and an error.
Example:
local m = hob.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)
endhob.model.available()
hob.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. For a
provider that keeps several accounts, it is what the focused session’s
account offers, the list /model shows there.
Returns: (table|nil, string|nil) Array of "provider/id" specs, or nil and an error.
Example:
local specs = hob.model.available()hob.model.set()
hob.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:
hob.model.set("anthropic/claude-opus-4-6")
hob.model.set({ spec = "zai/glm-5", thinking = "high" })
-- Alt+T already opens the /thinking picker, so the toggle takes Alt+Y.
hob.keymap.set({ "n", "i" }, "<M-y>", function() hob.model.set({ thinking = "" }) end)hob.model.usage()
hob.model.usage({opts?})Reads provider quota, the numbers /usage shows: the plan,
each limit window, and today’s spend per model where the provider reports
them. The shared in-memory cache separates providers, accounts and credentials,
so two tabs on one provider but different accounts each read their own quota.
The initial request subscribes the provider to central 5-minute refreshes
while any live session uses it. By default, returns a cached result newer
than 5 minutes or fetches one, joining any pending fetch. refresh = true
forces a fresh fetch but still joins one already pending. Unsupported
providers stay cached until forced or the providers are rebuilt. Outside the
TUI, pass both provider and account to read an existing cached observation.
These explicit account reads never fetch or choose preferred credentials.
Missing entries or multiple active credentials return an error. The headless
session snapshot has no account binding, so it cannot select quota implicitly.
Call initially and on ModelChanged or SessionFocusChanged, then handle
ProviderUsageChanged for updates without polling. Its result is published
to the cache before event delivery.
Parameters:
{opts?}(table|nil) Options:provider(string) Provider slug. Omit for the focused session’s provider. An explicit slug selects the focused session when it uses that provider, and any other live session using it otherwise, with selection and provider matching done atomically.account(string) Exact opaque saved-account id. Requiresproviderand reads only the shared cache, in either TUI or headless mode. Does not resolve account labels, prefixes, defaults, or environment credentials.refresh(boolean) Force a fresh fetch (default false). Unavailable with an explicitaccount.
Returns: (table|nil, string|nil) {plan?, limits, by_model_today?, quota_status}.
quota_status is {stale, refresh_status, observed_age_ms?, error?}.
observed_age_ms is the age in milliseconds of the last successful quota
report, absent if none was observed. Freshness is independent of
refresh_status (not_fetched, refreshing, ready, unsupported,
or failed). Stale never means exhausted. Failed refreshes retain the
last report, with the error in quota_status. Without a report, cached
states return {limits = {}, quota_status = ...}, including unsupported
providers and explicit account reads during a pending fetch. Missing or
ambiguous cache entries and requests that fail without a report return
nil and an error. ProviderUsageChanged also carries quota_status,
including when its usage is nil.
Each limit is {label, percentage?, used?, limit?, reset_at?, detail?}.
percentage runs 0 to 100, exact quantities use the provider’s native units,
and reset_at is epoch milliseconds.
Each by_model_today row is {model, input_tokens, output_tokens, total_tokens, spend_microdollars}.
Example:
local usage, err = hob.model.usage()
for _, limit in ipairs(usage and usage.limits or {}) do
print(limit.label, limit.percentage)
endhob.model.tier()
hob.model.tier({name}, {provider?})The model hob uses for a tier, the same one a subagent asking for that
tier gets: user’s pick from the /model picker for that tier (whatever
provider it names), else the curated default within provider, else any
provider. assigned tells a pick apart from a default. Pass provider to
prefer its models, the way subagents prefer the session’s provider.
Resolving a models.dev model can wait for that catalog to download, so
like get, this can’t 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 = hob.model.tier("weak", hob.model.get().provider)
if m then hob.model.set(m.spec) endhob.model.info()
hob.model.info({spec})Resolve a model spec to everything hob 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 = hob.model.info("anthropic/claude-opus-4-6")
if m and m.subsidised_by then print(m.subsidised_by, m.pricing.input) endhob.net
HTTP and plain TCP 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
hob.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.
local res, err = hob.net.request("https://example.com")
if res then print(res.body) endhob.net.request()
hob.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,
hob’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 (default 5 MB).retry(integer) Retries on 5xx errors (default 3).follow_redirects(boolean) Follow redirects (default true). When false, return the 3xx response without requesting its target.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 hob.provider.http_error.
body holds the raw bytes, so a binary download can go straight to
hob.fs.write. Tool results and hob.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 = hob.net.request("https://httpbin.org/get")
if err then
print("failed: " .. err)
else
print(res.status, res.body)
endhob.net.connect()
hob.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
hob.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).
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: (hob.net.Conn?, string?) The connection, or nil plus an error string.
Example:
hob.async.spawn(function()
local conn, err = hob.net.connect("127.0.0.1", 7777)
if not conn then return hob.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)hob.net.Conn
A TCP connection opened by hob.net.connect.
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 hob.log.error(err) end
if not chunk then print("peer closed") endConn: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(hob.json.encode(msg) .. "\n")
if not ok then return hob.log.error(err) endConn:close()
Conn:close()Close the connection. A read or write in flight ends with an error. Extra calls do nothing.
hob.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.
hob.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" } },
})hob.provider.register()
hob.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 hob 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.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
hob.provider.http_error. Hob 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, includingbase_urlvalues inplans. Abasecan use an origin fromauthor the plugin slug’s env/config override. See base routing.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 inhob auth login, which saves the key. Needs theenvpermission.default_model(string) Model id without the slug, selected afterhob auth login.login_url(string) Pagehob auth loginopens to get a key.plans(table) List of{ key, display_name, base_url, default_model, login_url }forhob 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 forcodec = "openai", all optional: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.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".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. A header the credentials set wins.host,content-length,transfer-encodingandconnectionare refused.extra_body(table) Merged into every request body.session_id(table) Sends the session id, as{ header = "x-affinity" },{ body_field = "prompt_cache_key" }, or both at once.thinking_overrides(table) Model id prefix to"no","yes"or"required", overriding the model table. Longest prefix wins.
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 hob process changed them. Spend a refresh token only on"refresh". Omittingbase_urlkeeps the current one.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.effortnarrows theopenai.thinkingdialect 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 inhob auth login. Thisctxalso hasctx.print(text),ctx.prompt({ label = ..., secret = ... })andctx.open_url(url).logout(function)function(ctx), run byhob auth logoutbefore Hob deletes the stored credentials itself. Only needed for work Hob cannot do, such as revoking a token upstream.
Requires the net plugin permission.
Parameters:
{spec}(table) Provider specification (see above).
Example:
hob.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 = hob.provider.auth.get(ctx.slug) or {}
return { headers = { Authorization = "Bearer " .. (creds.token or "") } }
end,
})hob.provider.is_selected()
hob.provider.is_selected({slug})Whether this package was granted {slug}: the manifest lists it under
providers and the install approval covers it. Kept from hob 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
hob.provider.http_error()
hob.provider.http_error({res})Turn a failed hob.net.request response into a provider error. A hook
returns it as return nil, err, and Hob 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 fromhob.net.request.
Returns: (userdata) A ProviderError. Opaque, but tostring renders it.
Example:
fetch_usage = function(ctx)
local res = assert(hob.net.request(ctx.base_url .. "/usage", { headers = ctx.headers }))
if res.status ~= 200 then
return nil, hob.provider.http_error(res)
end
return { limits = {} }
endhob.provider.auth
Credential storage for the providers this plugin registered.
Each slug gets one JSON file at
~/.local/state/hob/auth/plugins/<slug>.json, with mode 0600, atomic
writes and a lock against other Hob processes. The plugin decides what
goes in it. A plugin can only reach slugs it registered itself.
hob.provider.auth.set("acme", { access_token = tok, expires = when })
local creds = hob.provider.auth.get("acme")
hob.provider.auth.clear("acme")hob.provider.auth.get()
hob.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 = hob.provider.auth.get("acme")
if creds then print(creds.access_token) endhob.provider.auth.set()
hob.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 = hob.provider.auth.set("acme", { access_token = token })
if not ok then hob.log.error(err) endhob.provider.auth.clear()
hob.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:
hob.provider.auth.clear("acme")hob.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".
exists, current, read, export, messages, first_user_prompt,
user_prompts, notify and new without prompt or focus still
work. ACP has no focused session, so there current fails and the
history readers need session.
hob.session.list()
hob.session.list({opts?})Lists stored sessions, newest first. By default the ones in the
storage.session_scope config, the same set /resume and -c see.
scope picks another set: "cwd" for the sessions started in the
current working directory, "repo" for the ones started anywhere in its
git repository, linked worktrees included, and "all" for every stored
session, so a plugin can group them its own way. Answered from a
background scan, so a slow disk never blocks the UI.
Each row may also carry parent, the id of the session it was forked
from, and repo_root, the git checkout that holds its folder now. A
folder deleted along with its checkout still answers with the checkout it
was saved in. repo_subfolder is where the folder sits in repo_root,
“” at its root. It is found as the root is, through links, so it holds
when cwd keeps a spelling that does not start with repo_root.
Each row also tells what the session’s last save says, read from the
head and the tail of its log, so a listing parses no transcript:
created_at (Unix seconds), model (provider/id, “” until a turn picks
one), mode (“build” or “plan”), thinking (spelled like the setting),
fast, usage (the same fields as hob.session.read(), subagents
included, as the log wrote them, absent when the log records none),
context_size, and runtime_ms, how long its turns ran.
cost is what its turns recorded they billed, in dollars, and
list_cost the list price a flat subscription covered. Either is absent
when nothing recorded one: an unpriced model, or turns from before hob
recorded prices. size and archive_size are the bytes of its log and
of the logs a compaction or a rewind parked beside it. subagents and
reviews are {count, cost?, list_cost?}, priced as the session is: the
agents its tasks ran, and its autoreview cycles, one reviewer each. A fork
leaves out the tasks it kept from its parent.
Parameters:
{opts?}(table?)scope(string?) “cwd”, “repo” or “all” (default: thestorage.session_scopeconfig).
Returns: (table|nil, string|nil) Array of {id, title, cwd, updated_at, created_at, model, mode, thinking?, fast, usage?, cost?, list_cost?, context_size, runtime_ms, size, archive_size, subagents, reviews, parent?, repo_root?, repo_subfolder?}, or nil and an error.
Example:
local stored, err = hob.session.list({ scope = "repo" })
for _, s in ipairs(stored or {}) do
print(s.cwd, s.title)
endhob.session.default_scope()
hob.session.default_scope()The storage.session_scope config: the set /resume, -c and
hob.session.list without a scope look at.
Returns: (string|nil, string|nil) “cwd”, “repo” or “all”, or nil and an error.
Example:
local scope = hob.session.default_scope()hob.session.exists()
hob.session.exists({id})Checks whether a session has stored history, without reading its content. Counts unreadable or corrupt session files as present. A live session that has never been saved may return false. Metadata only, so no permission is needed. Works without a UI.
Parameters:
{id}(string) Session id.
Returns: (boolean|nil, string|nil) Whether storage exists, or nil and an error.
hob.session.live()
hob.session.live({opts?})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.
paused is whether the user paused it. cwd is the directory the
session records, as hob.session.read reports it. parent, repo_root,
repo_subfolder and the fields from created_at to reviews mean what
they mean for hob.session.list, but come from memory, so they take in
the turn that runs.
Every live session by default. scope keeps the ones that scope of
hob.session.list would take in, by the same rule, so the two lists of
one scope always agree.
Parameters:
{opts?}(table?)scope(string?) “cwd”, “repo” or “all” (default: every live session).
Returns: (table|nil, string|nil) Array of {id, title, cwd, status, paused, updated_at, focused, created_at, model, mode, thinking?, fast, usage?, cost?, list_cost?, context_size, runtime_ms, size, archive_size, subagents, reviews, parent?, repo_root?, repo_subfolder?}, or nil and an error.
Example:
local live, err = hob.session.live({ scope = "repo" })hob.session.current()
hob.session.current()Returns the id of the focused session. Under hob -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 = hob.session.current()hob.session.read()
hob.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
(hob.session.export, hob.session.messages).
The returned table:
{
id, cwd, model, mode = "build" | "plan",
account, -- the account's label as the status bar shows it,
-- nil for a stored session, or unless the provider
-- keeps several accounts
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
runtime_ms, -- accumulated main-session turn time, including the active turn
cost, -- nil for a stored session
queue = { count }, -- nil under headless drivers and for a stored session
title, -- nil under headless drivers without stored sessions
title_ownership = "unknown" | "automatic" | "manual",
title_revision,
}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 hob.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 = hob.session.read()
if s.context_size > s.context_window * 0.8 then
hob.ui.flash("context is nearly full")
endhob.session.export()
hob.session.export({opts?})Reads a session as the document hob session export prints, the same
table hob.session.new takes back:
{ format, model, mode, thinking, fast, title, facts, messages }messages defaults to what hob.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 hob has open can be read too.
JSON null comes back as hob.NIL and arrays are tagged, so
hob.session.export(...) encodes to the same document as the CLI file.
Copy it with hob.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.full(boolean?) Include pre-compaction messages. Defaults to false (retained context only).
Returns: (table|nil, string|nil) The document, or nil and an error.
Example:
local doc = assert(hob.session.export({ session = hob.session.current() }))
hob.fs.write("/tmp/session.json", hob.json.encode(doc))hob.session.messages()
hob.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?, display_in_place?, display_markdown?, receipts?, settles?, partial?, 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
hob.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). display_in_place, when true, shows a non-task
observation’s line at its history position instead of after the next user prompt.
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. 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 = hob.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 hob.NIL.
A live session is read from memory, unsaved messages included, any other
from disk. Works in the TUI, hob -p, sdk mode, and ACP. ACP has no
focused session, so pass session there. Hook and event payloads carry
the session_id to pass.
Requires the session_read plugin permission.
Parameters:
{opts?}(table?) Options:session(string?) Session id, live or stored. Defaults to the focused one.last(integer?) only the newestlastmessages.
Returns: (table|nil, string|nil) Array of messages, or nil and an error.
Example:
local msgs = hob.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)
endhob.session.first_user_prompt()
hob.session.first_user_prompt({opts?})Reads the first nonblank visible user prompt in the available history.
Uses display_text when present, otherwise joins the message’s text blocks.
Skips host messages, hidden messages, images and tool results. Only the
prompt text is copied into Lua, not the rest of the transcript.
Reads live unsaved history when available, otherwise the stored session. After compaction this is the first retained prompt, which may differ from the session’s original request.
Requires the session_read plugin permission.
Parameters:
{opts?}(table?) Options:session(string?) session id, live or stored. Defaults to the focused one.
Returns: (string|nil, string|nil) Prompt text, nil when none exists, or nil and an error.
hob.session.user_prompts()
hob.session.user_prompts({opts?})Reads the visible user prompts in the available history, oldest first.
Picks each prompt like first_user_prompt: display_text when present,
otherwise the message’s text blocks joined. Skips host messages, hidden
messages, images and tool results. Does not copy the rest of the transcript
into Lua.
Reads live unsaved history when available, otherwise the stored session. After compaction the history keeps only the prompts since then, and the compaction’s own “What did we do so far?” request counts as a prompt.
The array is tagged, so an empty one still encodes as [].
Requires the session_read plugin permission.
Parameters:
-
{opts?}(table?) Options:session(string?) session id, live or stored. Defaults to the focused one.last(integer?) only the newestlastprompts.with_metadata(boolean?) return{ text, autoreview }tables instead of strings.
autoreviewis true for a repair prompt sent by autoreview, false otherwise.
Returns: (table|nil, string|nil) Array of prompts, oldest first, or nil and an error.
Example:
local prompts = hob.session.user_prompts({ last = 3 }) or {}
for i, text in ipairs(prompts) do
print(i, text:sub(1, 40))
endhob.session.focus()
hob.session.focus({id}, {opts?})Switches the UI to the session with {id}. With cwd, hob moves to that
folder too, as /cd does, and a stored session opens there before any
prompt it kept queued runs. A session of another checkout of the same
repository moves its file records there in that one move, so a code
rewind puts back the files of cwd.
Parameters:
{id}(string) Session id, as returned bylist()orlive().{opts?}(table?)cwd(string?) the folder to open the session in (default: where hob is).
Returns: (boolean|nil, string|nil) true on success, or nil and an error.
Example:
local _, err = hob.session.focus(id, { cwd = "/path/to/worktree" })hob.session.delete()
hob.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 = hob.session.delete(id)hob.session.new()
hob.session.new({opts?})Creates a session from the document hob.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
hob -p and sdk mode the project of the session they run, under ACP the
directory hob 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. Either way it starts
on the default accounts, never on the focused tab’s.
Without prompt or focus the session is only stored, and
hob.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 (hob -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 hob.image.Image or the
{ type = "base64", media_type, data } table hob.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 hob.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. An imported title is manual, including after an export/import round trip, so automatic naming cannot replace it.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(hob.session.export({ session = id }))
local copy, err = hob.session.new(doc)
-- start a fresh one right away
local id, err = hob.session.new({ prompt = "fix the tests", focus = true })hob.session.import_json()
hob.session.import_json({json}, {opts?})Imports a raw JSON transcript without converting its payloads to Lua values.
Uses the same defaults, history repair and validation as hob.session.new.
Fields in the JSON document never submit a prompt or control focus.
Requires the agent and session_write plugin permissions.
Parameters:
{json}(string) Raw JSON object with amessagesarray.{opts?}(table?)focus(boolean) opens and focuses a new tab; otherwise stores it.
Returns: (string|nil, string|nil) New session id, or nil and an error.
hob.session.prompt()
hob.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 = hob.session.prompt("run the tests", { session = id })hob.session.notify()
hob.session.notify({text}, {opts?})Reports {text} to a live session without creating a user turn. The observation waits for the session’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.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:
hob.session.notify("[monitor] deploy failed", { session = id, wake = true })hob.session.set_mode()
hob.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:
hob.session.set_mode("build", { session = opts.session })
hob.session.prompt("Implement the plan at `" .. opts.path .. "`.", { session = opts.session })hob.session.set_title()
hob.session.set_title({opts})Renames a session, live or stored, and marks its title as manual.
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 = hob.session.set_title({ id = id, title = "refactor" })hob.session.set_automatic_title()
hob.session.set_automatic_title({opts})Updates a live or stored session’s automatically owned title only if its title revision still matches. Manual and unknown titles are never changed. Blank titles, stale revisions and ineligible ownership return false, not an error. An accepted unchanged title returns true.
Requires the session_settings plugin permission.
Parameters:
{opts}(table) Required fields: id (string), title (string), expected_title_revision (integer) fromhob.session.read.
Returns: (boolean|nil, string|nil) Whether the update was accepted, or nil and an error.
Example:
local accepted, err = hob.session.set_automatic_title({ id = id, title = "refactor", expected_title_revision = snapshot.title_revision })hob.Timer
Handle returned by hob.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 = hob.defer_fn(function() rebuild() end, 300)
h:stop()hob.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.
hob.task.list()
hob.task.list()Lists every chat in the focused session, in chat order. Entry 1 is always the
main chat, with id "main" and no status: its work is the session’s own, and
hob.session.live() already reports that. Other entries include subagents,
moved background calls and their reported parts. A tool-spawned subagent has
its tool call’s id; one a plugin opened with
hob.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?, review?, subagent?, part?, wrapper?, started_at?, ended_at?, cost?, list_cost?, model?, thinking?, fast?, usage?, context_size?, context_window?}, 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.
subagent is true for a chat backed by an agent session, including plugin-created,
nested and finished agents. It is absent rather than false for the main chat and
non-agent calls or parts; TaskStatusChanged instead always sends a boolean.
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. review
is the id of the autoreview task whose cycle was running when a call of the main
chat, like one of a repair turn, opened the task. /tasks lists a subagent that
has one under that task. 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 whose running children are
counted instead of the call.
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.
Subagents also expose their model spec, thinking level, fast mode, and
cumulative token usage (the same fields as
hob.session.read()), context size/window, and subsidised list_cost when
known. These fields describe that task alone, not its descendants. Missing
stats from older sessions or non-agent tasks remain absent; they never fall
back to the main chat’s stats.
Example:
for _, t in ipairs(hob.task.list() or {}) do
print(t.name, t.status or "main")
endhob.task.focus()
hob.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 = hob.task.focus("main")hob.task.stop()
hob.task.stop({id}, {opts})Stops a task in the focused session, including moved calls and their parts. Unlike a subagent tab, a read-only moved-call tab only returns to main on Esc; use this API to stop it. 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, hob.async tasks, and
commands run through hob.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 late reply
returns no output, and the result reaches the agent later as a quiet
notice. A task another agent moved, a finished task or an unknown id
returns an error that names the agent’s running task ids.
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?}. name is the task’s
name in hob.task.list(), and output is the final reply, missing when late.
Example:
local _, err = hob.task.stop(task.id, { session = task.session })
-- in a tool handler
local stopped, err = hob.task.stop(ctx, input.id)hob.task.send()
hob.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.
An agent reaches the subagents it moved, and those nested in a call it
moved, until they end. Like stop(ctx, id), it never reaches what
another agent moved.
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, or
nil and "no running background subagent with id <id>".
Example:
local sent, err = hob.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 .. "."hob.task.messages()
hob.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
hob.session.messages returns. It reaches what send(ctx, id) does.
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>".
Example:
local msgs = hob.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)
endhob.text
Text utilities: format conversion, UTF-8 decoding and the fuzzy matcher the built-in pickers use.
local md = hob.text.html_to_markdown(html)
local text = hob.text.to_utf8(bytes)
local hits = hob.text.fuzzy_list("mrs", names, { limit = 10 })hob.text.html_to_markdown()
hob.text.html_to_markdown({html})Convert an HTML string to Markdown.
Useful for cleaning up web content fetched with hob.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 = hob.text.html_to_markdown("<h1>Hello</h1><p>world</p>")
if err then return end
print(md) -- "# Hello\n\nworld"hob.text.to_utf8()
hob.text.to_utf8({s})Return {s} as valid UTF-8, with every invalid byte sequence replaced by
U+FFFD. Lua strings are bytes, and hob.net and hob.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 = hob.net.request(url)
local text = hob.text.to_utf8(resp.body)hob.text.markdown_code_ranges()
hob.text.markdown_code_ranges({text})Return the original source ranges of Markdown code spans and code blocks. Uses CommonMark with tables enabled and math disabled.
Parameters:
{text}(string) UTF-8 Markdown source.
Returns: (table?, string?) Ordered pairs of 1-based inclusive byte offsets, including delimiters, or nil and an error.
Example:
local ranges, err = hob.text.markdown_code_ranges("Use `code` here")
if err then return end
print(ranges[1][1], ranges[1][2]) -- 5, 10hob.text.fuzzy()
hob.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 hob.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 = hob.text.fuzzy("mrs", "hob-ui/src/main.rs", { paths = true })
if score then print(("hob-ui/src/main.rs"):sub(at[1][1], at[1][2])) endhob.text.fuzzy_list()
hob.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 hob.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(hob.text.fuzzy_list(query, names, { limit = 10 })) do
print(m.text, m.score)
endhob.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 = hob.treesitter.get_parser(source, "lua")
local trees = parser:parse()
local root = trees[1]:root()hob.treesitter.get_parser()
hob.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 = hob.treesitter.get_parser(src, "lua")
if err then print("error: " .. err) endhob.treesitter.get_string_parser()
hob.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.
hob.treesitter.get_node_text()
hob.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 = hob.treesitter.get_node_text(node, source)
print(text)hob.treesitter.get_node_range()
hob.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 = hob.treesitter.get_node_range(node)hob.treesitter.get_range()
hob.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 = hob.treesitter.get_range(node)
print("bytes: " .. r[3] .. "-" .. r[6])hob.treesitter.is_ancestor()
hob.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)
hob.treesitter.is_in_node_range()
hob.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)
hob.treesitter.node_contains()
hob.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)
hob.treesitter.get_node()
hob.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.
hob.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.
hob.treesitter.language.add("lua")
hob.treesitter.language.register("lua", "luau")hob.treesitter.language.add()
hob.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 hob.treesitter.language.add("lua") then return endhob.treesitter.language.register()
hob.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:
hob.treesitter.language.register("tsx", { "tsx", "jsx" })hob.treesitter.language.get_lang()
hob.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:
hob.treesitter.language.register("tsx", { "tsx", "jsx" })
local lang = hob.treesitter.language.get_lang("jsx") -- "tsx"hob.treesitter.language.get_filetypes()
hob.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 = hob.treesitter.language.get_filetypes("tsx")
-- { "tsx", "jsx" }hob.treesitter.language.inspect()
hob.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 = hob.treesitter.language.inspect("lua")
print("ABI: " .. info.abi_version)
for _, nt in ipairs(info.node_types) do print(nt) endhob.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 = hob.treesitter.query.parse("lua", "(string) @str")hob.treesitter.query.parse()
hob.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 = hob.treesitter.query.parse("lua", "(identifier) @id")hob.treesitter.query.get()
hob.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.
hob.treesitter.Query
A compiled tree-sitter query.
Get one by calling hob.treesitter.query.parse(lang, query_string).
Then use :iter_captures() or :iter_matches() to run it against a syntax tree.
local q = hob.treesitter.query.parse("lua", "(identifier) @id")
for idx, node, meta in q:iter_captures(root, source) do
print(node:type())
endQuery: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 = hob.treesitter.query.parse("lua", "(identifier) @id")
for idx, node, meta in q:iter_captures(root, source) do
print(idx, node:type())
endQuery: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 = hob.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
endhob.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 LuaTree: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.
hob.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)
endNode: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())
endNode: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
endNode: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.
hob.treesitter.LanguageTree
Manages parsing of a source string for a single language.
Obtained from hob.treesitter.get_parser() or hob.treesitter.get_string_parser().
Call :parse() to get the syntax tree, then use :root() on the tree to start walking nodes.
local parser, err = hob.treesitter.get_parser(source, "lua")
if not err then
local trees = parser:parse()
local root = trees[1]:root()
endLanguageTree: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.
hob.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 = hob.ui.buf()
buf:line("hello from my plugin!")
local win = hob.ui.open_win(buf, { title = "Greeting", width = "50%", height = 5 })Without a UI (hob -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,status_bar, andinput_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 |
A key that types TODO: at the cursor:
hob.keymap.set("i", "<M-t>", function(ev)
local st = ev.input
hob.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 hob.ui.input,
ev.input and ev.text in a key handler, and a binding on a key that
types text, see
hob.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 hob.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.
hob.ui.buf()
hob.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 = hob.ui.buf()
out:line("hello world")
-- A float raised during a tool call needs its own buffer:
local toast = hob.ui.buf({ scratch = true })
toast:line("copied!")hob.ui.theme_color()
hob.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
hob.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 = hob.ui.theme_color("accent")
if accent then
buf:line({ { "note", { fg = accent, bold = true } } })
endhob.ui.theme_style()
hob.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 hob.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 hob.ui.theme_color. Nil when the name is unknown, and an
empty table when the theme leaves that style unset.
Example:
local sel = hob.ui.theme_style("item_selected")
local dim = hob.ui.theme_style("dim")
buf:line({ { "note", { fg = dim.fg, bg = sel.bg } } })hob.ui.highlight()
hob.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 = hob.ui.highlight("fn main() {}", "rust")
for _, spans in ipairs(lines) do
buf:line(spans)
endhob.ui.markdown()
hob.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 = hob.ui.terminal_size()
local lines = hob.ui.markdown("# Hello\n\nSome **bold** text.", size.cols)
for _, spans in ipairs(lines) do
buf:line(spans)
endhob.ui.humantime()
hob.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:
hob.ui.humantime(90) -- "1m30s"
hob.ui.humantime(3661) -- "1h1m1s"hob.ui.terminal_size()
hob.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 = hob.ui.terminal_size()
local half_width = math.floor(size.cols / 2)hob.ui.display_width()
hob.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 = hob.ui.display_width("hello")hob.ui.truncate_text()
hob.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 = hob.ui.truncate_text("hello world", 5)
-- t.head == "hello", t.tail == " world"hob.ui.set_mode()
hob.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:
hob.fn.mode() returns it and the next key is matched against it. If
your plugin unloads while the input is in normal mode, hob switches it
back to insert mode.
Throws on any mode but "n" and "i".
Parameters:
{mode}(string)"n"or"i".
Example:
hob.keymap.set("n", "i", function() hob.ui.set_mode("i") end)hob.ui.flash()
hob.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:
hob.ui.flash("Copied to clipboard!")hob.ui.action()
hob.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 /? |
|
"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 hob.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 hob.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 hob.ui.input_submit. For slash commands, see hob.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`:
hob.keymap.set("n", "u", function() hob.ui.action("undo") end)
-- A key for a built-in that has none:
hob.keymap.set({ "n", "i" }, "<M-r>", function() hob.ui.action("input_raw") end)hob.ui.open_editor()
hob.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 = hob.ui.open_editor("/tmp/scratch.lua")
if code ~= 0 then
hob.ui.flash("editor exited with " .. code)
endhob.ui.open_win()
hob.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.
A rewind closes every window of the tab too. Cancelling a turn closes the
tab’s windows except panel ones, which stay as the plugin’s standing view.
Either way recv answers a close event.
Parameters:
{buf}(Buf) Buffer to display.{opts}(table) Float configuration. Fields:width(integer|string) outer window width, including borders. Integer for absolute columns; “N%” for percent of available width. Default “60%”.modal(string) opt in to a namedui.modalswidth for a focused floating window. The host resolves its percentage of available outer width on every render, including after reload. Unknown names keepwidth; omitted by default.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).position(string) which side of the chat input box apanelwindow stacks on. One of “above_input” (default) or “below_input”. A “below_input” panel sits between the input box and the status bar. Ignored by other splits and floats.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, inhob.keymapnotation, e.g.{ "<Tab>", "<CR>" }.hob.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 globalhob.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>,<C-z>,<C-\>,<C-4>,\and<M-\>are reserved for quit, suspend, the LazyGit toggle and literal backslash insertion, and are refused even for trusted plugins.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. Ahob.async.runtask keeps the tool call’s session, ahob.async.spawntask does not.
Returns: (Win) Window handle.
Example:
local buf = hob.ui.buf()
buf:line("Pick an option:")
local win = hob.ui.open_win(buf, {
title = "Menu",
width = "50%",
height = 10,
cursor_line = true,
footer = { { "q", "quit" }, { "Enter", "select" } },
})hob.ui.set_status_hint()
hob.ui.set_status_hint({spans}, {opts?})Shows styled text on the right of the input box’s top border for your plugin, for a key hint or a small live value. Each span is a {text, style} pair, where style is a theme style name. Every plugin’s spans share the border, joined in plugin name order. By default your spans 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 spans there, and are cleared when the session leaves the tab. The plan form’s own hint takes the border while it shows. Only your own spans are affected, other plugins keep theirs. To put an item in the status bar itself, see hob.ui.status_bar.
Parameters:
{spans}(table|nil) Sequence of {text, style} pairs, e.g.{{" 3/5 ", "foreground"}, {"Ctrl+T", "keybind_key"}}. nil clears your spans foropts.session, or all your spans ifopts.sessionis not set.{opts}(table?)session(string): id of the session whose tab shows the spans, e.g.ev.data.session_idorctx:session_id(). Default: every tab.
Example:
hob.ui.set_status_hint({ { " 3/5 ", "foreground" }, { "Ctrl+T", "keybind_key" } })
-- later, clear them:
hob.ui.set_status_hint(nil)
-- Only in the tab of the session that is running a turn:
hob.api.create_autocmd("TurnStart", {
callback = function(ev)
hob.ui.set_status_hint({ { "Esc", "keybind_key" }, { " cancel", "foreground" } }, { session = ev.data.session_id })
end,
})
hob.api.create_autocmd("TurnEnd", {
callback = function(ev)
hob.ui.set_status_hint(nil, { session = ev.data.session_id })
end,
})hob.ui.set_window_title()
hob.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 hob 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:
hob.ui.set_window_title("hob: " .. session_name)
-- Give the title back to the shell:
hob.ui.set_window_title("")hob.ui.input()
hob.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.vim_mode(string|nil)"normal"or"insert"while vim mode is on, nil while it is off. Normal mode types nothing, so a plugin that reacts to typing can skip it.
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 = hob.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 byteshob.ui.input_rules()
hob.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 ofhob.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:
hob.ui.input_rules({
ns = "skill",
pattern = [[\$skill:([\w-]+)]],
mark = { conceal = " $1 ", hl = "accent", atomic = true },
})
-- And remove it again:
hob.ui.input_rules({ ns = "skill" })
-- Bold text without its stars, unless the cursor is on it:
hob.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 } },
},
},
})hob.ui.input_decorate()
hob.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:
hob.api.create_autocmd("InputChanged", {
callback = function(ev)
hob.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,
})hob.ui.input_edit()
hob.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 hob.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
hob.keymap.set("i", "<Paste>", function(ev)
local st = ev.input
pastes = pastes + 1
local done = hob.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 = hob.ui.input()
if not st.anchor then return end
local s, e = math.min(st.anchor, st.cursor), math.max(st.anchor, st.cursor)
hob.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,
})hob.ui.input_submit()
hob.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.
When the selected / command is missing required arguments, it is
completed in the input instead of sent, just like Enter. If completion would
leave the input unchanged, the command runs so its handler can show usage.
Optional arguments do not prevent sending. Completion returns false without an error and is
attributed to your plugin. Completion additionally needs input permission;
without it the call fails and leaves the input unchanged.
Read hob.ui.input() again for its new version
before editing or submitting the completed input.
Use it to send what a key handler wrote, since ev.fallback() on <CR>
refuses text that changed after the press, see
hob.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, likehob.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 whathob.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, fromhob.ui.input,ev.inputorinput_edit.session_id(string) the tab the version was read from.
Returns: (boolean|nil, string|nil) true once sent, false when completed without sending, or nil and an error.
Example:
-- Spell out `lgtm` before sending:
hob.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 = hob.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
hob.ui.input_submit({ version = version, session_id = st.session_id })
end)hob.ui.Win
Handle to a floating or split window. You get one from
hob.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 = hob.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 canonicalhob.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.reserved_bottom(integer) rows reserved at the bottom of the content area.split(string) edge docking, “above”, “below”, “left”, “right”, “panel”, or “”.position(string) side of the chat input box apanelwindow stacks on, “above_input” or “below_input”.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 lineWin: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" })
endWin: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.
hob.ui.Buf
A content buffer that holds styled lines of text. Create one with
hob.ui.buf() and pass it to hob.ui.open_win() to show it in
a floating or split window.
local buf = hob.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, hob.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)")
endBuf: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-tripBuf: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)
hob.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 = "█" })hob.ui.status_bar
The one-row bar at the bottom of the screen. A plugin adds its own items to it, and hides the built-in items it shows another way, or the whole bar. Without a UI these calls change nothing on screen.
hob.ui.status_bar.set("timer", { { " 1m 07s ", "accent" } }, { side = "left" })
hob.ui.status_bar.hide({ "cwd", "model" })hob.ui.status_bar.set()
hob.ui.status_bar.set({name}, {spans?}, {opts?})Adds your plugin’s item {name} to the status bar, or replaces it. Left items come before errors and flash messages. Right items come before the built-in working directory and model. Within a side, a lower {order} draws first, and plugin name then item name break ties. Right items step aside while an error holds the bar, as the built-in ones do. While a plugin hides the whole bar, the items move with the messages to the bottom border of the input box, left items before the messages and right items after them. Unloading your plugin removes its items.
Parameters:
{name}(string) Your name for the item, unique within your plugin.{spans?}(table|nil) Sequence of {text, style} pairs, ashob.ui.set_status_hinttakes. nil or an empty table removes the item.{opts?}(table?)side(string) “left” or “right” (default “right”).order(integer) where the item sits on its side (default 50).
Example:
hob.ui.status_bar.set("timer", { { " 1m 07s ", "accent" } }, { side = "left" })
-- later, take it away:
hob.ui.status_bar.set("timer", nil)hob.ui.status_bar.hide()
hob.ui.status_bar.hide({names})Hides built-in status bar items, for a plugin that shows the same thing
its own way, such as an info panel. An item stays hidden while any plugin
hides it, and unloading your plugin undoes its hides. Flash messages,
errors, [workflow] and [restricted] always show.
“bar” hides the whole bar and gives its row to the chat. The bottom border
of the input box then shows the spinner, the messages, the plugin items
and the labels, but no other built-in item. While the input box is gone or
too small for the labels, as under a prompt, a form or a below split, the
bar comes back.
Parameters:
{names}(string[]) Any of “bar” (the whole bar), “cwd” (folder and branch), “model”, “thinking”, “fast”, “context”, “cost”.
Example:
hob.ui.status_bar.hide({ "cwd", "model", "thinking", "context", "cost" })hob.ui.status_bar.show()
hob.ui.status_bar.show({names})Undoes your own hide for {names}. A hide from another plugin still
holds.
Parameters:
{names}(string[]) Nameshidetakes.
Example:
hob.ui.status_bar.show({ "cwd" })hob.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 = hob.uv.os_homedir()hob.uv.cwd()
hob.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 = hob.uv.cwd()
if cwd then print("working in: " .. cwd) endhob.uv.os_homedir()
hob.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 = hob.uv.os_homedir() -- e.g. "/home/user"hob.uv.os_getenv()
hob.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 = hob.uv.os_getenv("EDITOR") or "vi"hob.yaml
YAML encoding and decoding. Works the same way as hob.json,
but for YAML formatted strings.
local t = hob.yaml.decode("greeting: hello")
print(t.greeting)hob.yaml.encode()
hob.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 = hob.yaml.encode({ name = "hob", tags = { "ai", "agent" } })
print(s)hob.yaml.decode()
hob.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 = hob.yaml.decode("name: hob\nversion: 1")
print(t.name) -- hobShared helper modules
These ship inside hob; require them from any plugin. Small modules are
shown as full source, larger ones as their public interface.
require("hob.color")
-- The contrast a faded text keeps against the background: hob's floor for
-- labels and dimmed text (MIN_LABEL_CONTRAST in hob-ui/src/theme.rs), so a
-- plugin's dimmed text reads like hob's own on light and dark themes.
M.MIN_CONTRAST = 3.0
function M.lerp(from, to, t)
-- The WCAG 2 contrast ratio of two "#rrggbb" colors, from 1 to 21. Nil when
-- either is a palette color, which has no value to measure.
function M.contrast(a, b)
-- {color} moved {factor} of the way toward {background}, but only as far as
-- MIN_CONTRAST allows, so faded text stays readable. A color already below
-- the floor is kept as it is. Nil when either color is not "#rrggbb".
function M.fade(color, background, factor)
-- {color} moved toward {toward}, a theme's text color, until it reaches
-- MIN_CONTRAST on {background}, so a fixed color stays readable on any theme.
-- A color that already reads is kept. Nil when a color is not "#rrggbb".
function M.readable(color, background, toward)
-- M.fade toward the theme background. Nil when the theme names palette
-- colors, so the caller can fall back to the terminal's dim attribute.
function M.dim(color, factor)require("hob.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("hob.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("hob.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), modal (optional `ui.modals` identity)
-- 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
--
-- Keys you pass go through `hob.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.cut = cut
ListPicker.clamp_parts = clamp_partsrequire("hob.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]"
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("hob.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("hob.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("hob.scroll")
-- Relative scrolling on top of hob.fn.winsaveview / winrestview.
-- Positive {delta} scrolls down, negative up. Returns (true, nil) or (nil, err).
local function scroll(delta)
local view, err = hob.fn.winsaveview()
if not view then
return nil, err
end
return hob.fn.winrestview({ topline = view.topline + delta })
end
return scrollrequire("hob.shorten_path")
local function normalize_sep(s)
return s:gsub("\\", "/")
end
local function shorten_path(path)
local p = normalize_sep(path)
local cwd = hob.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 = hob.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_pathrequire("hob.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("hob.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)
-- Render only the cursor's logical line with {prefix}, horizontally scrolled
-- within {width} cells to keep the cursor visible without wrapping. Returns
-- one styled line (a span array), not { lines, cursor_row }.
function TextInput:render_scrolled(prefix, width)require("hob.toast")
-- Corner toast notifications built on floating windows. `hob.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("hob.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 `hob.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("hob.truncate")
--- require("hob.truncate")(text, max_lines, max_bytes)
--- Cuts {text} to the limits and notes how many bytes it dropped. A nil limit
--- is unlimited.