/luvus-module

name: luvus-module
description: >-
  Write a luvus module (an extension for luvus, mission control for your AI coding agents). Use when
  the user is building or debugging a luvus module: authoring luvus-module.toml,
  adding a sidebar dock, Luvus Bar widget, right-click action, event hook,
  module pane, module settings, or calling luvus back over its UHP.

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 meth