Writing a luvus module

A luvus module is a plugin for luvus, mission control for your AI coding agents. There is no SDK and no scripting engine: a module is a directory with a luvus-module.toml manifest that declares argv commands (any executable: sh, python, node, a compiled binary). luvus runs those commands as subprocesses with LUVUS_* context in the environment, and the command calls luvus back through the same UHP the luvus CLI uses. So a module in bash/python/node can do what a built-in feature does.

Reference material in this repo (read for depth): MODULE-GUIDE.md, docs/13-modules.md, and the worked modules in examples/modules/ (branch-dock = a sidebar dock, agent-ping = an event hook, scratch-pane = a pane).

The manifest: luvus-module.toml

Top-level keys (all required unless noted):

id = "yourname.my-module"     # unique, reverse-dns style
name = "My Module"
version = "0.1.0"
min_luvus_version = "0.8.3"   # oldest luvus this needs
description = "One line."      # optional
platforms = ["macos", "linux"]  # optional; omit = all. Also per-item.

Then any of these tables, each declaring an argv command (a list, run as-is, cwd = the module dir):

• [[docks]] id, title, placement (sidebar.left | sidebar.right) — reserve a sidebar dock. luvus renders it; you fill it with ui.dock.push (see below).
• [[bars]] id, title, region (top-right | bottom-right), optional priority — reserve a bounded one-row Luvus Bar widget. Publish structured segments with luvus bar push (ui.bar.push on the UHP); live content is not persisted.
• [[startup]] command — run once when the session is up and the socket is listening (and on enable). Dock rows and bar content are not persisted, so this is how you repaint them after a restart.
• [[events]] on, command — run when a luvus event fires. Valid on values include workspace.created/closed, tab.created/closed/moved, pane.created/closed/forked/moved, pane.agent_status_changed, agent.hook, and the task.*/lease.* events (see KNOWN_EVENTS in src/module/manifest.rs for the full set — an unknown on is a hard manifest error).
• [[actions]] id, title, command, optional contexts — a runnable action. With contexts = ["pane"|"workspace"|"node"|"agent"|"tab"] it also appears in that right-click menu, acting on what was clicked. Without contexts it is CLI-only (luvus module run <id> <action>). Dock rows also invoke an action on click.
• [[panes]] id, title, command, placement (split | overlay | tab) — a real pane running your command (luvus module pane open <id> <entrypoint>).
• [[settings]] key, title, type (bool | string | number | enum), plus default, options (enum), min/max/step (number), secret (mask + hide the value). Rendered in Settings → Modules; values reach every command as env (below).
• [worktree_provider] one optional fixed creation command, optional fixed remove_command, and optional platforms. The user selects the module id in config.json at worktree.provider; config cannot replace either command.

A worktree provider reads one versioned JSON request from stdin. Creation gets version, operation, repository, branch, and branch_exists, and must print only {"path":"/absolute/worktree/path"} on stdout. Removal gets version, operation, repository, path, branch, and force; it must print nothing, exit successfully, and unregister and remove the target. If a provider violates its exit or stdout contract after deletion already completed, Luvus reconciles the proven Git/filesystem state instead of retaining a stale workspace; stdout remains unsupported. Human logs go to stderr. This command is synchronous and must not call back into the Luvus CLI/API while the server waits. Luvus verifies the returned path is a registered worktree of the source repository on the exact requested branch before opening a workspace; explicit removal is verified before and after the command. Internal rollback and task merge remain Git-backed.

What your command receives (no JSON parsing needed)

luvus puts context in the environment, flat, so a bash module never parses JSON:

• LUVUS_MODULE_ID, LUVUS_MODULE_ROOT (the module dir), LUVUS_MODULE_VERSION
• LUVUS_MODULE_TOKEN — UI-publisher credential for this server; the Luvus CLI forwards it automatically, so do not persist or override it
• LUVUS_MODULE_CONFIG_DIR, LUVUS_MODULE_STATE_DIR — writable per-module dirs
• LUVUS_WORKSPACE_ID, LUVUS_WORKSPACE_CWD, LUVUS_TAB_INDEX
• LUVUS_PANE_ID, LUVUS_PANE_CWD, LUVUS_PANE_AGENT, LUVUS_PANE_STATUS (the clicked/target pane)
• LUVUS_SETTING_<KEY> for each declared setting (uppercased key), plus the whole set as JSON
• [worktree_provider] commands read their versioned operation request as JSON from stdin
• Dock-row clicks add LUVUS_MODULE_DOCK_ID, LUVUS_MODULE_ROW_ACTION, LUVUS_MODULE_ROW_VALUE, LUVUS_MODULE_ROW_TEXT, LUVUS_MODULE_ROW_INDEX
• Bar-segment clicks add LUVUS_MODULE_BAR_ID, LUVUS_MODULE_BAR_SEGMENT, and optional LUVUS_MODULE_BAR_VALUE
• LUVUS_MODULE_CONTEXT_JSON — the full snapshot, if you want structured data
• LUVUS_SOCKET_PATH, LUVUS_BIN_PATH — to call luvus back (below)

What your command can do: call luvus back

Run the luvus CLI from inside the command; it talks to the running server over $LUVUS_SOCKET_PATH. Use "$LUVUS_BIN_PATH" to guarantee the same binary as the session. Module-facing methods:

• luvus ui dock push --id <dock> --rows <json> (or pipe the JSON on stdin) — fill your dock. Rows are {text, dot?, tone?, spans?, action?, value?, menu?}; a row's action invokes one of your [[actions]] on click, with the row's value in LUVUS_MODULE_ROW_VALUE. tone is a Luvus Bar tone name (normal, muted, accent, success, warning, error) for the text, and spans is [{text, tone?}] to color segments of one row with the same tone names (a span without a tone takes the row's). Both are optional and theme-bound, raw colors and ANSI are not accepted. Omitting tone gives the default row color, which is not the same as normal.
• luvus bar push --id <widget> --content <json> — atomically publish structured text, symbol, state, badge, progress, spacer, and separator segments. Add --compact-content; an action must name one of your [[actions]].
• luvus ui notification push --text <text> --level info|success|warning|error — publish bounded transient status; use --dedupe-key for replacement.
• luvus ui toast "<text>" — flash a one-line confirmation.
• luvus ui agent-title push --titles <json> — publish AGENTS sidebar titles for live panes (pane) and resumable sessions (built-in agent + session_id). OSC still wins; never send a Luvus =alias as the title. luvus ui agent-title clear drops one key or every title owned by your module. The CLI authenticates ownership automatically.
• luvus ui sidebar / ui dock list / ui dock move — sidebar/dock control.
• luvus tab rename <name> / tab list — tabs.
• luvus module settings <id> / module settings <id> <key> — read your settings exactly (values are masked in settings list when secret, but exact in settings get).
• Plus the whole CLI: luvus pane split/run/send, luvus agent ..., luvus git ..., etc.

Recipes

A sidebar dock (like examples/modules/branch-dock): declare [[docks]], a [[startup]] that runs a script which builds a JSON rows array and calls ui dock push, and [[events]] so it refreshes on workspace.created/tab.created. Give rows an action matching a [[actions]] id to make them clickable.

A Luvus Bar widget (like examples/modules/ci-bar): declare [[bars]], publish full and compact structured content from a one-shot startup/event action, and keep expensive work outside the render path. Use a pane for arbitrary terminal UI and a dock for multi-row content.

An event hook (like agent-ping): a [[events]] with on = "pane.agent_status_changed" and a command that reads LUVUS_PANE_* and reacts (notify, log, ui toast).

A right-click action: an [[actions]] with contexts = ["pane"] (or workspace/node/agent/tab). It appears in that menu and runs against the clicked target's LUVUS_* env.

A pane: a [[panes]] entry; open it with luvus module pane open <module-id> <entrypoint>.

Test loop

luvus module link <path-to-module-dir>     # register a local module (dev)
luvus module list                          # confirm it's runnable
luvus module log [<id>]                     # tail command output/errors while iterating
luvus module run <id> <action>              # invoke an action directly
luvus module enable <id> | disable <id>

Iterate: edit the script, re-run the action or trigger the event, watch module log. The manifest is validated on link; a broken manifest keeps the entry visible but not runnable, with the reason in module info <id>.

Conventions

• One module, one job. Keep commands fast and quiet — luvus caps a command's output (64 KiB) and runs at most 32 at a time.
• Identity env (LUVUS_MODULE_ID, LUVUS_MODULE_TOKEN, socket path) is injected and cannot be overridden. Never log or persist the token.
• Use platforms on the manifest or any item to skip a build step / hook / pane / action where it does not apply.
• To share it: luvus module install <owner>/<repo> clones + builds + registers from GitHub; tag the repo with the luvus-module topic so luvus module search finds it.