Using velmux

A background server owns every pane, so you can close your terminal or detach (<prefix> d) and come back with velmux: everything keeps running.

The sidebarCopy Anchor Link

From the top:

• ⊕ new space adds a repo: it lists the git repos in your scratch_dir (default ~/Workspace) that aren't in the sidebar yet, or type a path. Also <prefix> N.
• ≡ menu: a short menu of app-wide actions (themes, settings, restart, detach, stop). Also <prefix> m.
• spaces · agents switches views (<prefix> g). The agents view lists every agent with where it is and what it's doing, the ones that need you first; click one to jump to it.

The spaces view lists each repo with its checkout (◆ base) and its claimed slots (▣, branch first, slot number dimmed; free slots are a count on the repo's line). Below them, parked branches (◌) waiting to be resumed. Below a divider are scratch sessions: shells (or anything) outside any repo; the divider's + (or <prefix> S) starts one in your scratch_dir.

Each row shows its agents' states on the right:

Slot rows also show their health and PR: ↓3 behind the base, ! a rebase or merge stopped on conflicts, ⋯ still being set up, #142✓ its PR and checks (see Working in slots).

Right-click a row for what you can do there. A repo: start a conversation, claim a slot, a shell, rename, remove. A slot: Claude in it, sync with the base, its PR, open in the browser on its port, a shell, release. A parked branch: resume or discard. A session: Claude or a shell in it, rename, remove.

Drag a repo or a session to reorder; a line shows where it will land. Nothing collapses, so the layout never shifts as you move around.

Tabs and panesCopy Anchor Link

Every place (a repo's checkout, a slot, a session) has its own tabs, and each tab is a split layout, so a slot can show Claude beside a test-runner shell. Tabs sit in the header, named after what they run (or what you call them), with their agents' states, so a background tab still tells you when it's done or blocked. Click one to switch, + for a new one, scroll over the header to cycle, ⌃0 (or <prefix> ;) to flip back to the last one.

Panes are labelled by what's running and where (shell · packages/web, bun, nvim).

KeysCopy Anchor Link

Press the prefix (ctrl+b by default) and a popup lists every key you can press next:

Prefix-less shortcutsCopy Anchor Link

Any action can be bound with no prefix. The defaults follow a ⌘-driven layout:

They use key codes apps never receive, so they can't clash with an app's own keys, but your terminal has to send them: velmux keys --ghostty prints the Ghostty config lines, and velmux keys --test shows what your terminal sends. Rebind anything in the config.

MouseCopy Anchor Link

Click a pane to focus it, a sidebar row to go there, a tab to switch. Drag a divider to resize. The wheel scrolls a pane's history (and closes it again at the bottom), sends arrow keys to full-screen apps like less, and passes straight through to apps that ask for the mouse (vim with mouse=a, full-screen TUIs). Hold Shift (Option in iTerm2) for your terminal's own selection.

CopyingCopy Anchor Link

Drag over text in any pane to copy it, even in apps that use the mouse; a click that doesn't move still reaches the app. Double-click copies a word, triple-click a line. Copies go to the clipboard and to your terminal (OSC 52), so they work over SSH too.

Copy mode (<prefix> [) freezes the focused pane and opens its history. vi keys move (hjkl, ^u ^d ^b ^f, g G, 0 $), v / V select by character or line, y or Enter copies and exits, / and ? search (smartcase), n N repeat, q or Esc exits.

<prefix> ] opens the pane's whole history as plain text in $VISUAL / $EDITOR, in a new tab.

Finding a conversationCopy Anchor Link

⌘⇧F (or <prefix> /) searches every Claude conversation in your repos, their slots and your sessions: titles, your prompts and Claude's replies. Every word has to match; title matches come first, then the newest. Each hit shows where it ran, its branch, how long ago, and ● if it's open right now. Enter goes to it, or resumes it: in its slot if that's still on its branch, by resuming the branch if it's parked, else in the repo.

NotificationsCopy Anchor Link

When an agent finishes while you're not looking at it, or is blocked on you, velmux shows a desktop notification (through your terminal, or the OS when you're detached) and plays a sound. "Looking" means its pane is focused and your terminal window is in front: a Claude finishing in the pane you left while you read docs in a browser still chimes. Merged PRs and failing checks on your slots notify too.

Pick the sounds with sounds… in the menu: a column for "finished" and one for "blocked on you", each played as you move to it, Enter to keep. velmux ships herdr-done / herdr-request (from herdr), confirm, glass, pluck, question and bong (from Kenney), and its own chime and knock; see NOTICE. Turn sounds or notifications off in the config.

ThemesCopy Anchor Link

<prefix> ctrl+t (or the menu) previews themes live: arrows to look, Enter to keep (saved to your config), Esc to go back. Built in: default (your terminal's palette), rose-pine, rose-pine-moon, rose-pine-dawn, catppuccin-mocha, catppuccin-latte, tokyonight, gruvbox, nord. Override any colour in the config.

Restarting and restoringCopy Anchor Link

velmux saves everything as it changes. After a stop (<prefix> Q, velmux stop), a crash or a reboot, velmux brings it all back: shells and editors reopen, each Claude resumes its exact conversation in the slot it ran in, and every pane's scrollback is replayed above it.

velmux restart (or <prefix> ctrl+r) restarts the server in place: panes keep running, screens and scrollback are kept, and your terminal reconnects by itself. With auto_restart on (the default) this happens whenever the velmux binary changes, so upgrading is just installing.

If the screen ever looks wrong, <prefix> ctrl+l redraws it (and nudges every pane to re-read its size).

UpdatesCopy Anchor Link

velmux checks velmux.com for a newer version when it starts and twice a day (a plain request for the latest version: nothing about you or your repos is sent). When there's one you're told once, and ≡ menu shows ↑. Update velmux… in the menu (or velmux update) updates it the way you installed it: Homebrew runs brew upgrade in a new tab; a downloaded binary (the install script, a release archive) is downloaded, checked against its checksum and swapped in place, and the running velmux restarts into it. velmux update --check only says whether there's a newer one. Turn checks off with update_check = false.