Workspaces & panes

A workspace is a named folder — usually a repo — plus a layout of panes. A pane is one real terminal running one agent or a plain shell. Those two ideas carry the whole app.

Workspaces

Every workspace you create stays open. Switching between them never touches a process: agents in the workspace you just left keep working, and their output is waiting when you come back. The left rail lists them all, each row expanding into its panes, and badging how many of its agents want you.

Workspaces load lazily. At launch only the one you're looking at starts; the others start on first visit, with their agents resuming their previous conversations where the CLI supports it. A loaded workspace you're done with for now has a Sleep button in the rail: its processes stop and its memory is freed, while the workspace, its layout, and its conversations stay exactly as they were. The next visit brings it back. If agents are mid-work you get a confirm first.

Deleting a workspace kills exactly its agents and nothing else. Drag rail rows to reorder them, and the order is the order Cmd/Ctrl+K w 1…9 switches through.

Multi-repo workspaces

Point a workspace at a folder that contains several repos — frontend/, backend/, website/ — and the app notices. The creation screen tells you what the folder holds, the git panel reviews every child repo in its own section instead of offering to git init over the top of them, and branch pills ask which repo before they ask which branch. Detection is live: clone a repo into the folder mid-session and its section appears.

Panes

Each pane's titlebar carries, from left to right: a numbered status circle (the number is the pane's Cmd/Ctrl+N shortcut, so "which agent is 3" reads the same in the titlebar, the rail, and the git panel), the occupant's name and current task, a git branch pill, and buttons to maximize and close. A ⋯ menu holds Restart, Split right, and Split down.

Panes are terminals, so they scroll, select, and copy like terminals. Narrow panes shed titlebar parts in a fixed order rather than cramming everything in, and the full story — name, task, branch, progress — is always on the titlebar's tooltip.

• Focus a pane by clicking it or pressing Cmd/Ctrl+1…9.
• Maximize fills the grid area. While zoomed, focusing another pane retargets the zoom, so Cmd/Ctrl+1…9 flips through agents full-screen.
• Split from the ⋯ menu or p s / p d in command mode. A split opens a fresh pane beside this one.
• Rearrange by dragging a pane's titlebar: drop on another pane's center to swap the two, near its edge to insert beside it, or on the grid's outer edge to claim a full row or column. Drop it on a workspace in the left rail to move the pane — agent still running — into that workspace.
• Undo any restructure from the chip that appears afterwards.

Programs that report progress (winget, cargo, Claude Code) get a slim bar in the pane header, and their aggregate rides the dock icon or taskbar, so a long install is visible without the pane being on screen.

Layouts

New workspaces start from a template — 1×1, 1×2, 1×3, 2×2, 1+2, 3×3 — and grow from there: the top bar's + menu appends a pane, splits add them next to their parent, and the Arrange menu re-tiles whatever you currently have into a tidy grid, columns, rows, or main + stack, previewed as thumbnails before you commit.

Plain terminals

A pane can run your default shell instead of an agent. Terminals get lifecycle status only — no activity heuristics, no chimes — and agents never message them. On Windows you choose which shell they open in Settings → Terminal (Auto prefers PowerShell 7; Windows PowerShell, Command Prompt and WSL are one click away).

Activity states

Every running agent pane is in one of these, shown in its numbered status circle and in the rail:

Panes also draw an activity ring along their edge: amber and pulsing while attention is unacknowledged, and a green pulse when a run finishes that holds until you focus, click, or type. Either moment can also make a sound — a soft falling tone when a run finishes, the same shape an octave higher when an agent starts waiting for you. They are a fraction of a second long and told apart by shape rather than volume. Settings → General turns them off, keeps only one of the two, or limits them to when the app is in the background.

The status bar keeps the app-wide count across every open workspace, and its amber "needs input" item clicks through the waiting agents one at a time, switching workspaces as it goes.

Per-pane branches

The titlebar's branch pill is a switcher. Pick or create a branch and that pane moves into the branch's own git worktree — created on demand under ~/.vibeguild/worktrees/ — and its agent restarts there. No other pane moves, and nothing resembling a git checkout happens underneath them.

• Panes on the same branch share one worktree; git's one-checkout-per-branch rule is the model.
• A fresh worktree runs the workspace's setup command first (Settings → Worktrees, e.g. pnpm install), visibly in the pane, before the agent starts. Panes opened onto a worktree that is still setting up wait behind an overlay and start themselves when it finishes.
• Worktrees clean themselves up when their last pane closes. Dirty ones are never auto-deleted.
• In a multi-repo workspace the pill is two-step: pick the repo, then the branch, and it reads "frontend @ feature-x" afterwards. Each repo gets its own setup command.

Panes without their own branch share the working tree, so avoiding conflicts there is up to you. What each branch actually changed is reviewed in the git panel.

Quitting

Quitting kills every process the app started — no orphans, ever. If agents are mid-work, a confirm names how many (Settings → General, on by default), and closing a busy or waiting pane asks in the pane itself. A crash is repaired by a sweep at the next launch.