Writing hob plugins
Write a Lua plugin: tools, commands, keys, and UI, with the same API as the built-in ones.
Hob plugins are plain Lua files (Luau) that run inside hob. A plugin can
register tools the LLM calls, slash commands, keymaps, prompt hints, and
custom UI. Everything lives under the global hob table. The full API
reference is at the end of this document.
Where plugin code goes
Plugins live in the hob config dir. There are two of them, same layout:
~/.config/hob/- global, every project<project>/.hob/- this project only
init.lua the only file hob runs; require()s plugins, calls hob.setup()
lua/<name>.lua plugin modules, loaded by require("<name>")
plugin.toml permission grants for every Lua file in the dirNothing under lua/ loads on its own. A module name is its path under lua/
without the extension: lua/browser.lua is require("browser"),
lua/acme/tools.lua is require("acme.tools"). require is sandboxed to
that directory, you cannot reach files outside it.
Creating a plugin
- Write the code in
~/.config/hob/lua/<name>.lua. Thehobglobal is already there, nothing to import. For a project-only plugin use<project>/.hob/here and in every step below.
hob.api.register_tool({
name = "hello",
description = "Say hello to a name.",
parameters = { type = "object", properties = { name = { type = "string" } }, required = { "name" } },
handler = function(args)
return { llm_output = "hello " .. args.name }
end,
})- Load it from
~/.config/hob/init.lua, creating that file if missing:
require("hello")- Grant the permissions it needs in
~/.config/hob/plugin.toml, creating that file if missing. Without the file every gated call is denied.
[permissions]
fs_read = true
run = true- Run
/reload, then read the log as described below, to see that it loaded and what it printed.
hob.api.register_options is for bundled plugins and
packages. Hob rejects a plugins.<name> table whose name
is neither, and startup fails. A module you require from lua/ keeps its
settings in a local table, or exports a setup(opts) function that init.lua
calls.
Permissions and plugin.toml
Sensitive APIs are gated per plugin file, and a plugin without a
plugin.toml next to it gets nothing. The gates and the file format are
in the reference. Set
min_hob_version there when a plugin needs a newer Hob Lua API.
Development loop
/reload rebuilds plugins and config in place, no restart needed. Until it
runs, an edited plugin is still the old one.
To debug, add hob.log.info|warn|error(...) calls. They write to hob.log
in the dir hob.env.logs_dir() returns (Linux: ~/.local/logs/hob/). The
log keeps info and above. Set HOB_LOG=debug to also keep hob.log.debug,
or HOB_LOG=hob_lua=trace to narrow it to one target. When a backtrace comes
out useless, start hob with --no-jit: plugins then run on the interpreter,
with full debug info.
Conventions
- Fallible runtime calls return a
(value, err)pair; checkerrbefore usingvalue. - Tool handlers report failures with
{ llm_output = "error: ...", is_error = true }, not by raising. - The model picks tools by reading
description, so state precisely what the tool does and when to use it. - Reusable helpers ship with hob; see “Shared helper modules” in the API reference.
A complete real example
The bundled glob tool, verbatim: schema, header and restore hooks, error
handling, LLM output truncation, collapsible UI view. It is a bundled plugin,
so it opens with register_options, which your own plugin skips:
local truncate = require("hob.truncate")
local ToolView = require("hob.tool_view")
local shorten_path = require("hob.shorten_path")
local output_limits = require("hob.output_limits")
local NO_FILES_FOUND = "No files found"
local opts = hob.api.register_options(output_limits.extend({
search_result_limit = { default = 100, min = 10, desc = "Max files the model sees per search." },
}))
local function glob_view_opts(ctx)
local tol = ctx:tool_output_lines()
return { max_lines = (tol and tol.grep) or 3, keep = "head" }
end
hob.api.register_tool({
name = "glob",
permission = "fs_read",
kind = "search",
description = [[Find files by glob pattern.
- Respects .gitignore.
- Returns absolute paths sorted by modification time (newest first).
- Prefer speculative parallel searches over sequential rounds of glob+grep.]],
schema = {
type = "object",
properties = {
pattern = { type = "string", description = "Glob pattern (e.g. **/*.rs, src/**/*.ts)", required = true },
path = { type = "string", description = "Directory to search in (default: cwd)" },
},
},
header = function(input)
local buf = hob.ui.buf()
local spans = { { shorten_path(input.pattern or ""), "tool" } }
if input.path then
spans[#spans + 1] = { " in ", "dim" }
spans[#spans + 1] = { shorten_path(input.path), "path" }
end
buf:line(spans)
return buf
end,
restore = function(_input, output, _is_error, ctx)
return ToolView.restore(output, glob_view_opts(ctx))
end,
handler = function(input, ctx)
local pattern = input.pattern
if not pattern then
return { llm_output = "error: pattern is required", is_error = true }
end
local max_lines, max_bytes = output_limits.resolve(opts, ctx)
local files, err = hob.fs.glob(pattern, {
path = input.path,
gitignore = true,
sort = "mtime",
limit = ctx:output_mode() == "compact" and opts.search_result_limit or nil,
})
if not files then
return { llm_output = "error: " .. err, is_error = true }
end
if #files == 0 then
return { llm_output = NO_FILES_FOUND }
end
local lines = {}
for i, f in ipairs(files) do
lines[i] = shorten_path(f)
end
local text = table.concat(lines, "\n")
local llm_output = truncate(text, max_lines, max_bytes)
local buf = hob.ui.buf()
local view = ToolView.new(buf, glob_view_opts(ctx))
for _, line in ipairs(lines) do
view:append(line)
end
view:finish()
buf:on("click", function()
view:toggle()
end)
return {
llm_output = llm_output,
body = buf,
}
end,
})Full API reference
Every module, function, and method is in the Lua API reference.
The agent gets the same document on disk through the builtin
hob-plugin-dev skill, so asking it to write a plugin for you works
without pasting any of this.