Skip to content
Luvus

Your First Session

This is the whole luvus experience in five minutes. You’ll open a project, run an agent next to a shell, watch its status live, detach, and come back to find everything (including the agent’s conversation) exactly where you left it.

1. Launch in a project

Section titled “1. Launch in a project”
Terminal window
cd ~/code/my-project
luvus

The window has three areas: the sidebar (your workspaces and a live AGENTS list), the tab bar, and the pane area with a shell already running in your project folder.

Running luvus in a different folder later adds that folder as another workspace in the same session: one luvus, all your projects.

2. Split and run an agent

Section titled “2. Split and run an agent”

Press Ctrl+Space then v to split side-by-side (or s for stacked, or just use the mouse). In one pane, start your agent:

Terminal window
claude        # or copilot, codex, opencode, aider…

Watch the sidebar: the pane appears in AGENTS with a live state:

State Meaning
🟠 working producing output right now
🔴 blocked waiting on you (a permission prompt is on screen)
🟢 done finished while you weren’t looking
idle quiet

Click any agent row to jump to its pane. In Settings → General, choose a Retro, Soft, or Pulse sound style and enable the events you want to hear when an agent blocks or finishes.

3. Move around

Section titled “3. Move around”

Everything is mouse-first: click panes to focus, drag borders to resize, click tabs and sidebar rows, scroll with the wheel. The keyboard mirror: hold Ctrl+Space, then arrows/hjkl to focus, c for a new tab, z to zoom a pane, ? for the full cheat-sheet.

Scroll an agent’s history with two-finger scroll, or press Shift+↑ for scroll mode, where 1–9 jump through history and q snaps back to live.

Press Ctrl+Space then t to choose another named session. Switching local sessions keeps the client open and reconnects its display and input to the selected server. Both sessions keep their agents, shells, and pane processes running, so you can switch back and continue working. Normally, switching does not restart a server or resume agents into replacement processes. After a Luvus upgrade, selecting a session that is still running the previous version safely restarts that target session before handing the client over.

4. Detach: this is the magic

Section titled “4. Detach: this is the magic”

Press Ctrl+Space then q. The client exits, but nothing stops: your panes, shells, and agents keep running in the background server. Close the terminal app entirely. Go make coffee.

Terminal window
luvus    # …and everything is exactly where you left it

5. Survive a real restart

Section titled “5. Survive a real restart”

Even if the server itself stops (a reboot, luvus server stop), your session snapshot is saved continuously. The next luvus restores your workspaces, tabs, and layouts. It also resumes each agent’s own conversation via its native session store. A Claude Code pane comes back as the same Claude Code conversation, no --resume flags to remember.

The saved terminal image is a bounded copy of the live screen, not the portion of history you happen to be viewing. Scrolling before a save does not change that image. Wide characters, combining marks, and text styling are preserved when replayed at the same terminal size. This cosmetic image is separate from the agent’s native conversation store and is not a backup of all scrollback.

Where next

Section titled “Where next”