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 project workspace → the client stays attached and immediately opens one neutral terminal at your home directory. It uses the normal terminal surface, tabs, panes, and sidebar without a separate landing screen.
• 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.

On desktop, the active session name appears at the top-left in place of the static Luvus label. Select it or press Ctrl+Space t to open another running or stopped session, or to create and open a new one. Only the current display client moves; the previous server and its panes keep running. Session discovery and startup occur only when you open or use this menu, not on an idle timer.

2. Workspace → Tab → Pane

Session         normally contains one or more workspaces
└── Workspace   one per project folder (fixed project root, 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

• After the final project closes, Luvus creates a neutral workspace and real terminal rooted at your home directory. You can immediately type, create tabs or splits, change directory, or browse to another project.
• 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 project cwd stays fixed, while its displayed terminal path follows the focused pane’s live cwd. With several splits, focusing a different pane shows that pane’s path, and every pane keeps its own working directory.
• 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.