/luvus

name: luvus
description: "Control Luvus through its local CLI and UHP. Use only for a line beginning with `=target message`, an explicit request naming Luvus, a request to delegate to a named live Luvus agent or pane, or an explicit Luvus operation involving sessions, machines, workspaces, tabs, panes, agents, files, Git, DIFF, worktrees, tasks, leases, modules, themes, Luvus Bar, configuration, UI, integrations, or Luvus UHP. Do not use for ordinary coding, file edits, Git operations, tests, task planning, generic agent work, or parallelization unless the user explicitly connects the request to Luvus. Being inside Luvus does not trigger this skill by itself. Inside Luvus use the inherited session; outside use the installed production Luvus command and configured session."

Luvus

Use Luvus's semantic CLI and UHP to delegate work, control the live workspace, and build explicit harness integrations. The skill adds no service, event loop, or polling process.

Route `=target` delegation first

Treat `=target message` as Luvus delegation only when `=` is the first non-whitespace character on a line, `target` contains no spaces, and a message follows it. Do not treat equations, assignments, or `=` in prose as delegation. Codex skill invocations keep their `$skill-name` syntax.

Examples:

• `=reviewer inspect this diff` sends `inspect this diff` to the agent named

`reviewer`.

• `=7 run the migration` addresses pane 7.
• `=codex add tests` addresses the unique agent named or kinded `codex`.

For every delegation line:

1. Run `luvus agent send <target> "<message>"` directly without `--wait`. `agent send` resolves live names, numeric pane ids, and unique agent kinds authoritatively. Do not run `agent list` first. 2. On success, accept the returned pane, agent, name, and status, tell the user where the work was sent, and end the turn. Do not reread or poll. 3. Only after `not_found` or `ambiguous_target`, run `luvus agent list` once to show the live choices. Never guess or retry a different target without the user's choice. 4. For any other error, report it without listing agents. Never absorb or perform the delegated task locally after delivery fails. Start an agent only when the user clearly requested it.

Plain-language delegation requests follow the same workflow. Never delegate merely because another agent could help.

Select exactly one session

Never run bare `luvus` because it launches or attaches the TUI. Examples below say `luvus` for readability. Substitute the client selected here.

Inside a Luvus pane

When `LUVUS_ENV=1`, control the inherited session:

• Require `LUVUS_BIN_PATH`, `LUVUS_SOCKET_PATH`, and `LUVUS_PANE_ID`.
• Invoke the exact `LUVUS_BIN_PATH`. Let it use the inherited socket.
• Keep `LUVUS_PANE_ID` as the caller and default split anchor.
• Never replace the inherited socket or binary with a default, a PATH lookup,

or another Luvus session.

Act on the inherited session only because the user is already inside that session and explicitly asked for delegation or control.

Outside Luvus

Use the installed production Luvus client:

• Resolve `luvus` once with the current shell's command lookup, such as

`command -v luvus` on Unix or `(Get-Command luvus).Source` in PowerShell.

• Invoke that exact resolved path for the rest of the request. This supports

Luvus installed by Cargo, Homebrew, `install.sh`, or another PATH-managed installation.

• Preserve an explicitly configured `LUVUS_HOME` or `LUVUS_SOCKET_PATH`.

Preserve `LUVUS_SESSION` too. When the user explicitly names a server session, pass `--session <name>` directly to every related Luvus command. If that selects another server, Luvus discards the inherited pane id because pane identities are scoped to their issuing session. Do not list sessions first, and do not silently fall back to `default`. Otherwise let the installed release binary use its production default at `$HOME/.luvus/luvus.sock`.

• Never substitute `LUVUS_BIN_PATH` or a repository build for a missing

installed command.

• Only after an attempted Luvus action cannot run because command lookup finds

no `luvus` client, report that Luvus is not installed and stop. Offer one of the supported commands: `curl -fsSL https://luvus.dev/install.sh | sh`, `brew install RizRiyz/luvus/luvus`, or `cargo install luvus`. Do not show this guidance preemptively or for socket, permission, server, or other command failures. Do not imply Luvus is available until a later lookup succeeds.

• Start the production server only when the user asked to start or use Luvus

and starting it is a normal required step.

In the Codex app, local socket access may require permission outside the workspace sandbox. Request that permission for the selected Luvus client. Do not describe an unapproved sandbox failure as an offline server. Only report the production server offline after an approved command cannot connect.

Use the same selected binary and socket for the entire request.

Manage named server sessions

A named session is an independent Luvus server and PTY tree, not a workspace. Use these commands only when the user explicitly asks to inspect or manage server sessions:

luvus session list
luvus session attach <name>
luvus session stop <name>
luvus session delete <name>
luvus --session <name> pane list

`pane list` discovers pane IDs across all workspaces and tabs in that session without changing focus. Add `--current-tab` to limit the result to the active tab.

`session attach` launches or attaches the TUI. Never run it merely to test whether a session exists. `session stop` ends every pane in that named server. Before deletion, list sessions once, require the exact stopped name, and obtain clear authorization. Never delete `default` and never substitute workspace commands for server-session commands.

Manage saved SSH machines

A saved machine is an SSH profile owned by the selected local