Using Modules

A module extends luvus with sidebar panels, panes, Luvus Bar widgets, right-click actions, and automations. Modules are ordinary programs in any language, declared in a small manifest. There’s no SDK and no plugin runtime, so a module is just a repo with some scripts in it.

If you want to build one, see Writing a Module. This page is about running other people’s.

Finding modules

There is no registry and no marketplace account. A module is a public GitHub repo tagged with the luvus-module topic, and both the terminal and the website read that same topic:

luvus module search              # most-starred first
luvus module search git status   # narrow it with keywords

Or browse the module index on the site.

module search needs curl or wget and talks only to GitHub’s search API. It is read-only and never touches your running session, so it’s safe to run any time.

Installing

luvus module install owner/repo              # the whole repo is the module
luvus module install owner/repo/path/to      # a module in a subdirectory
luvus module install owner/repo --ref v1.2   # pin a branch, tag, or commit

Install is deliberately a conversation, not a one-shot. It:

1. Shallow-clones the repo to a staging directory.
2. Prints every command the module declares and asks you to confirm.
3. Runs any [[build]] steps with a scrubbed environment (no LUVUS_* and no socket access), so a build script can’t drive your session.
4. Verifies the manifest didn’t change during the build.
5. Moves the checkout into luvus-managed storage and records the exact commit.

A real install looks like this:

Install module from RizRiyz/luvus-agent-ping
  id:      example.agent-ping
  name:    Agent Ping 0.1.0
  commit:  5d3687f1528e
Commands this module can run:
  action ping-now: python3 ping.py --force
  on pane.agent_status_changed: python3 ping.py
installed example.agent-ping (RizRiyz/luvus-agent-ping@5d3687f1528e…)

Read that command list before you say yes. It is the whole security review, and it is short on purpose. An action opted into Commander also shows its $ name, target, input, and confirmation policy in this preview.

Use --yes to skip the prompt in scripts and CI, and only for sources you already trust. To refresh an installed module, use module update rather than installing over its registered ID.

Updating

luvus module update example.agent-ping
luvus module update owner/repo/path/to
luvus module update owner/repo --ref v1.2

Select the session that owns the module; its server must be running and support module.update. The CLI downloads and builds a separate checkout using the same command preview, approval prompt, scrubbed build environment, and manifest immutability check as installation. --yes skips approval only for trusted sources. No background update checks or automatic upgrades run.

Updates preserve the module ID, settings, config/state directories, and current enabled/disabled state. A saved --ref is reused unless you explicitly supply a different one. Without a saved ref, the source’s default branch is used. Older installations did not store their selected ref: supply --ref again on their first update if you want to retain a pin.

Only after a successful build does the server validate that the old source, checkout, and ref still match, persist the replacement, and refresh module UI and startup hooks. Download/build failures, changed module IDs, and concurrent replacement conflicts leave the registered version unchanged. Locally linked modules must be updated and built in their own working directory.

Existing module panes and commands are not restarted. Their old checkout is retained so their working directory remains valid; new invocations use the new checkout. Old publisher credentials are retired, so reopen an old module pane if it needs to publish docks or bars. Retained old/unadopted checkouts are not automatically garbage-collected; uninstall removes only the current checkout.

Configuring

Modules can declare their own settings. Open Settings → Modules (Ctrl+Space then the Menu button, or click Menu in the sidebar) and you’ll see each module with its settings indented beneath it:

• Toggles flip with ⏎ or a click.
• Numbers and choices step with the ‹ › arrows.
• Text opens a small prompt on ⏎. Values marked secret show as •••••• and are never echoed back.

Settings are collapsed while a module is disabled, so the list stays short.

The same values are reachable from the CLI, which is handy for setup scripts:

luvus module settings you.ci               # every key, its type, current value
luvus module settings you.ci limit         # read one
luvus module settings you.ci limit 30      # write one

A listing reports a secret only as "set": true|false, never its value, since that output usually lands in your scrollback. Ask for the key by name when a script genuinely needs it.

Anything a module stores itself lives in its own directory:

luvus module config-dir you.ci   # prints (and creates) it

Managing

luvus module list                # what's installed, and whether it's runnable
luvus module info <id>           # its actions, panes, docks, events, source
luvus module enable <id>
luvus module disable <id>
luvus module run <id> <action>   # invoke an action by hand
luvus module log [<id>]          # captured stdout/stderr + exit status
luvus module uninstall <id>      # unregister + delete a managed checkout
luvus module unlink <id>         # unregister only, leave the files alone

For an action that declares a Commander command, open Commander, clear its initial @pID with Ctrl+U, and type $ to browse. See the Commander guide for target syntax and confirmation.

Name it however you remember it

Anywhere a command takes <id>, you can pass either the module’s id or the owner/repo you installed it from. You should not have to remember that RizRiyz/luvus-agent-ping calls itself example.agent-ping just to remove it:

luvus module uninstall RizRiyz/luvus-agent-ping   # the name you installed with
luvus module uninstall example.agent-ping         # the module's own id

The two can never collide, because a module id may not contain a slash. Owner and repo are matched case-insensitively, like GitHub does. A module you linked from a local directory was never installed from anywhere, so only its id names it.

Everything here also works from Settings → Modules, where a click toggles a module on or off.

Disabling is the off switch you want. A disabled module runs nothing: no actions, no event hooks, no startup commands, and its docks and right-click entries disappear. Re-enabling it lets it repaint its docks immediately, without a restart.

uninstall only deletes files for modules luvus manages (installed from GitHub). For a module you linked from your own working directory it refuses, and tells you to use unlink instead, so it can never delete your source.

Where a module can show up

Once enabled, a module appears wherever its manifest said it should:

Surface	Where you’ll see it
Dock	A panel in either sidebar. Move it, or turn it off, in Settings → Layout
Pane	A real pane you open with luvus module pane open <id> <entrypoint>
Right-click	Extra rows below the divider in the pane, workspace, or agent menus
Settings	Its own section in Settings → Modules
Events	Invisible: it just runs when agents, panes, tabs, or tasks change

Docks are placed by the user, not the module. From Settings → Layout, each dock has [Left] [Right] [Off] buttons, so a module can suggest a side but never keep it.

Developing locally

While writing a module, register your working directory instead of installing:

luvus module link /path/to/my-module      # add --disabled to register it off
luvus module unlink you.my-module         # deregister; your files are untouched

link does not run [[build]] steps: build your own tree. Linking also runs the module’s startup hooks straight away, so a dock shows up without a restart.

Try the three examples that ship in the repo:

luvus module link ./examples/modules/branch-dock

Trust

A module is ordinary code that runs on your machine, as you, with your environment and your full luvus CLI. That openness is the point. It’s the same deal as an editor extension or a shell plugin, and the same judgment applies.

What luvus does for you:

• Shows every declared command before an install, and waits for confirmation.
• Runs build steps with a scrubbed environment and no socket access.
• Refuses an install if the manifest changed after you saw the preview.
• Pins the installed commit, so a later force-push doesn’t change what you ran.
• Keeps each module’s config and state in its own directory.
• Refuses to delete files it doesn’t manage.

What it does not do: sandbox. luvus doesn’t inspect or restrict what a module’s code does once you approve it. Install from authors you trust, skim the manifest and the scripts, and pin --ref when you want a specific revision.

Troubleshooting

Symptom	What’s happening
Listed but runnable: false	Disabled, gated to another OS by platforms, or its manifest failed to load. module list shows the warning.
An action is ambiguous	Two modules use the same action id. Qualify it: module run <module-id> <action>.
Nothing in the log	The entry stays running until the command exits. Output is capped at 64 KiB per stream.
A dock is empty	It repaints from a startup hook. If the module has none, run its refresh action once.
Right-click row missing	The module is disabled, or the action’s platforms exclude your OS.
module search fails	It needs curl or wget, and GitHub rate-limits anonymous search. Browse the topic instead.
Install refused	Installing over a locally linked module is blocked. unlink the local one first.