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 dir

Nothing 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

  1. Write the code in ~/.config/hob/lua/<name>.lua. The hob global is already there, nothing to import. For a project-only plugin use <project>/.hob/ here and in every step below.
lua
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,
})
  1. Load it from ~/.config/hob/init.lua, creating that file if missing:
lua
require("hello")
  1. Grant the permissions it needs in ~/.config/hob/plugin.toml, creating that file if missing. Without the file every gated call is denied.
toml
[permissions]
fs_read = true
run = true
  1. 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; check err before using value.
  • 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:

lua
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.

Keyboard shortcuts

Go to

On this page

  • jkNext or previous section
  • 12…The section with that number
  • cCopy the install command
  • iDownload
  • dDocs
  • []Previous or next page

Anywhere

  • ?Show or hide this list
  • EscClose, or stop a "g"