Scripting luvus

luvus’s UI and CLI are the same surface: a local JSON socket (~/.luvus/luvus.sock). Whatever you can click, you can script.

The essentials

luvus pane split --down                # split the focused pane
luvus pane run 7 cargo test           # run a command in pane 7
luvus pane read 7                      # print a pane's recent output
luvus wait output 7 --match "passed"  # block until text appears (exit 0; 2 on timeout)
luvus wait agent-status 7 --status done --timeout 600
luvus attach 7                         # open the TUI fullscreen into one pane
luvus events                           # stream every status change (ND-JSON)

Agents scripting luvus

Every pane gets $LUVUS_PANE_ID and $LUVUS_SOCKET_PATH injected, so commands inside a pane default to that pane, so an agent can split itself a scratch pane, run tests there, and wait on the result:

luvus pane split --down          # agent makes itself a helper pane
luvus pane run "$id" ./repro.sh
luvus wait output "$id" --match "done" --timeout 300

wait exit codes are script-friendly: 0 = condition met, 2 = timeout.

Watching everything

luvus events emits newline-delimited JSON for agent status changes, task and lease activity, and more, which is ideal for a monitor loop or an orchestrator agent. See orchestration for the task/lease command set, and run luvus help all for the complete reference.