Core Concepts

Five ideas explain everything luvus does.

1. A server owns your session, a client shows it

When you run luvus, two things happen: a background server starts (once) and owns every pane, shell, and agent, and a thin client attaches to display it. The client is disposable. The server is durable.

• Close the terminal (or Ctrl+Space d) → the client detaches, the session lives. Every shell and agent keeps running exactly where it was.
• luvus again → a new client attaches to the same live session. Nothing restarts and no command reruns, you are just looking at it again.
• Close every workspace → the server stays up with a fresh one. Nothing you do in the UI can kill the session by accident.
• luvus server stop → the only way to actually end everything (the session snapshot is kept).
• luvus server status → what’s running, and whether a newer binary is waiting for a luvus server restart.

If the server itself goes away (a reboot, an upgrade via luvus server restart, or the process being killed), luvus saves the session shape on the way out and rebuilds it on the next start: workspaces, tabs, layout, each pane’s folder and last screen, and any agent conversation it can resume natively. A resumed pane opens straight into its agent, nothing gets typed into a prompt in front of you. Live processes can’t outlive their owner, so shells come back fresh, but you land in the same place you left.

More than one independent session

The default luvus command keeps the same single durable server as before. If you need separate failure and resource boundaries, give each server a name:

luvus session attach api
luvus session attach website
luvus --session api pane list

A named session owns its own server, PTYs, agents, workspaces, tabs, snapshot, and orchestration ledger. It is not a workspace. luvus session stop api stops only api, while website stays responsive. luvus session list checks known sessions without starting any server or background manager.

2. Workspace → Tab → Pane

Session
└── Workspace   one per project folder (fixed cwd, shows its git branch)
    └── Tab     a layout of panes (or a special tab: git, orchestration)
        └── Pane   a real terminal running a shell or an agent

• Workspaces are the sidebar’s top list. Ctrl+Space N opens the folder picker. Running luvus inside a folder adds it automatically. A workspace’s cwd is fixed at creation, so cd-ing inside a pane never moves it.
• Tabs hold split layouts. Two special tabs exist: the git tab and the orchestration board.
• Panes are real terminals. Split with v/s, close with x, zoom with z, resize by dragging borders. See Panes, Tabs & Workspaces for the full mouse + keyboard reference.

3. The prefix key

luvus stays out of your keystrokes: everything you type goes straight to the pane. Commands live behind one chord: press the prefix (Ctrl+Space by default), release, then a key. Ctrl+Space ? lists everything, and every binding is remappable in Settings → Keys. The prefix itself is configurable (set it to Ctrl+b, or apply the tmux preset), so it can match your muscle memory. See Keybindings.

The two deliberate exceptions, so they work even where Ctrl+Space is taken: mouse everything, and Shift+↑ for scroll mode.

4. Agents are watched, not wrapped

luvus doesn’t inject itself into your agents. They run untouched in ordinary panes. Detection reads the screen: which agent is this, is a permission prompt showing (blocked), is output flowing (working), did it just go quiet (done). That’s why any agent works with zero setup, and a hook can add precision where you want it.

5. Everything is a command

The UI and the CLI are the same surface: whatever you can click, luvus <verb> can do over a local socket, and agents inside panes can too (each pane gets $LUVUS_PANE_ID and the socket path injected). This is what makes scripting and orchestration natural instead of bolted on.