luvus-module

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.