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.

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)