Control Luvus from Codex

The optional Luvus Codex skill provides agent delegation and full session control. It covers workspaces, tabs, panes, agents, files, Git, worktrees, tasks, leases, modules, and UI state.

Inside a Luvus pane, the skill uses that pane’s inherited binary, socket, and pane identity. This lets the same skill delegate and control the current Luvus session without guessing which server owns the pane.

Outside Luvus, the skill resolves the installed luvus command and controls its configured production session. With the default configuration this is the server at ~/.luvus/luvus.sock.

For a named server, include the selector in the request or command:

luvus --session api agent list
luvus --session api pane focus 7

The skill preserves the inherited socket inside a managed pane. Outside a pane, an explicit --session wins over any inherited socket. It does not run session list, help, or ping before an ordinary operation, so named-session routing adds no discovery round trip to the fast command path.

Enable the Codex skill

Luvus starts without installing skills or editing Codex configuration. Opt in when you want Codex to control Luvus:

luvus skill enable codex

The command downloads a signed release, verifies its package and file hashes, and installs it at ~/.agents/skills/luvus/, Codex’s native user-skill path. It does not add an always-on pointer to ~/.codex/AGENTS.md.

Start a new Codex thread after enabling the skill. Confirm its release, path, and integrity at any time with:

luvus skill status codex

Connect to Luvus

The skill supports two modes:

• Managed pane: Codex is running inside Luvus. The skill uses the injected LUVUS_BIN_PATH, LUVUS_SOCKET_PATH, and LUVUS_PANE_ID values exactly. It controls only that inherited session and never substitutes another socket or binary.
• External terminal: Codex is running in any other local terminal. The skill resolves the installed luvus command from PATH and uses its configured production session.

Approve local socket access in the Codex app

The Codex app normally runs shell commands in a workspace sandbox. Luvus uses a local Unix socket outside that workspace, so the app will ask for permission before ping or another control command. Approve the request if you want that thread to operate Luvus.

Without this approval, the operating system returns the same connection error as an offline server. The skill retries with explicit permission and reports Luvus access was not approved when permission is declined. It only reports the server offline after an approved connection attempt fails.

Do not disable the Codex sandbox globally. The skill requests only the local execution permission when it needs to connect to Luvus.

Install and start Luvus

The skill works with every supported Luvus installation method:

curl -fsSL https://luvus.dev/install.sh | sh
brew install RizRiyz/luvus/luvus

Only one installation method is needed. Confirm the command is available, then start the production server when it is not already running:

luvus --version
luvus server start

The skill supports custom production locations. If LUVUS_HOME or LUVUS_SOCKET_PATH is explicitly configured, it preserves that configuration. Otherwise the installed release uses ~/.luvus/luvus.sock. The skill never runs bare luvus for discovery because that launches or attaches the interactive TUI.

Ask Codex to control the session

Use $luvus when you want to invoke the skill explicitly:

Use $luvus to show the active workspaces, tabs, panes, and agents.

Inside Luvus, start a line with =target to delegate the rest of that line:

=reviewer inspect the current diff
=7 run the test suite
=codex fix the parser

The target can be a live agent name, pane id, or unique agent kind. The marker must be the first non-whitespace character on the line. $ remains reserved for Codex skill invocation.

Try requests such as:

Show me every coding agent running in Luvus.

Split a pane on the right, run the tests there, and show me the result.

Inspect the active workspace, Git state, tasks, and path leases.

Read the visible screen of the blocked Codex agent before answering it.

Fork an agent session

The skill can fork a supported live agent into a sibling pane while the original keeps running. Resolve the source first, then optionally name the new fork or preserve the current focus:

luvus agent get reviewer
luvus agent fork reviewer --name experiment --no-focus

The fork inherits the source conversation and receives its own new session. Native forks currently support Claude, Codex, and Pi. If the target is unsupported, its session cannot be resolved, or its pane cannot start, the skill reports Luvus’s structured error instead of substituting a split, new agent, or resume operation that could lose or reuse the wrong context.

Arrange panes and tabs

The skill can move a running pane to another tab without restarting its process, or append a new tab for it. Resolve the pane and inspect the tabs in its workspace before changing the layout:

luvus pane move 7 --tab 2
luvus pane move 7 --new-tab

It can also reorder tabs in the active workspace:

luvus tab list
luvus tab move 3 1

Tab positions are 1-based. A pane move stays inside that pane’s workspace, removes an empty source tab, keeps the process and terminal history alive, and follows the pane with focus. Reordering tabs keeps the same tab active even when its position changes. The skill uses explicit pane IDs and confirmed tab positions instead of inferring either from the visible sidebar.

The skill can also organize workspaces after resolving their stable 0-based indices:

luvus workspace list
luvus workspace rename 2 "Luvus website"
luvus workspace pin 2
luvus workspace unpin 2

Renaming changes only the label. Pinning changes display_position, not the workspace index, and keeps linked worktrees grouped with their parent.

From an external terminal there is no implicit caller pane. The skill resolves live IDs first and uses explicit targets for state changes. It also uses bounded reads and waits, preserves focus where possible, and asks before destructive operations such as closing panes, removing worktrees, merging tasks, or stopping the server.

Inside a managed pane, delegation sends work without waiting by default and keeps the current pane focused. When a result must return asynchronously, the sender can name itself and ask the worker to report back through agent send.

How agent readiness works

Luvus reports agent identity separately from lifecycle status. Once a pane is recognized as Codex, the skill considers idle, done, working, and blocked ready states. An idle or completed agent is ready for a stable name and a new prompt, so the skill does not wait for it to become working first.

For new agents, the skill prefers agent start, which launches, recognizes, and names the agent with one bounded command. wait agent-status is reserved for waiting on a specific lifecycle state after work has been sent.

From an external Codex terminal, agent start --anchor <pane-id> creates the new no-focus sibling beside an explicit pane and completes the launch in one invocation. Omit --down for a right-side split and add it for a split below. On an older installed release without --anchor, the skill uses pane split <pane-id> --no-focus followed by agent start --pane <new-pane-id>. This keeps Cargo, Homebrew, and install.sh releases compatible while newer versions use the faster path.

Fast command path

The skill does not run help or ping before every control command. A normal command already proves whether the production server is reachable. It also reuses resolved pane IDs and successful command results instead of immediately listing or reading the same state again.

Delegation calls agent send directly because the server already resolves live names, pane IDs, and unique agent kinds. A successful response returns the pane, agent, name, and status, so the skill does not prepend agent list. It lists agents once only after not_found or ambiguous_target, when live choices are needed to recover safely.

A successful agent start result with ready: true is complete. The skill does not follow it with another status or agent lookup. It waits only when the next requested action depends on a state transition or when you explicitly ask it to wait.

Common pane and agent instructions stay in the small core skill. Guidance for worktrees, orchestration, modules, UI, and destructive operations loads only when a request needs it, which keeps normal startup and control prompts lighter.

Update or remove

Update the enabled Codex skill, then start a new Codex thread:

luvus skill update codex

Without an agent argument, luvus skill update refreshes every enabled agent. It does nothing—and makes no network request—when no skills are enabled.

Remove only the managed Codex skill with:

luvus skill disable codex

Disabling the skill does not stop Luvus or change any Luvus session. If the managed files were modified, Luvus preserves them rather than deleting user changes.