Panes, tabs and workspaces

This page shows you how to arrange your work in wrkstrms. You split a tab into panes, move panes and whole tabs around, open and close tabs and workspaces, jump anywhere with the finder, and copy text out of panes with the mouse or the keyboard. It also explains how wrkstrms saves your layout and brings it back. For the ideas behind workspaces, tabs and panes, read Concepts first. Every key here is also in Keys and mouse.

In this page, prefix means Ctrl-Space.

Splitting panes

To	Do
Split the focused pane, new pane below	prefix s
Split the focused pane, new pane on the right	prefix v

The new pane runs your shell ($SHELL) and gets the focus. In a workstream tab, the shell starts in the workstream’s directory (see Workstreams).

You can also right-click a pane’s top border or a tab and choose Split right or Split below.

Each pane needs at least 6 columns and 3 rows. If there isn’t room, the top bar says not enough room to split and nothing changes.

Moving the focus

To	Do
Focus the pane to the left, below, above or right	prefix h/j/k/l, or Alt-h/j/k/l without the prefix
Go back to the pane you were in before	prefix ;
Focus a pane with the mouse	Click it
Jump to the next agent that needs you	prefix a or Alt-a

Moving left from the leftmost pane moves the keyboard into the sidebar, when the sidebar is shown. Press Esc or l there to come back.

Swapping panes

prefix H/J/K/L swaps the focused pane with its neighbor to the left, below, above or right. The focus moves with your pane, so you can press the key again to keep moving it.

Zooming

prefix z makes the focused pane fill the whole tab. Its title ends with [zoom]. Press prefix z again to put it back. Moving the focus to another pane, or swapping, also ends the zoom. A tab with only one pane can’t zoom.

Resizing

With the keyboard

prefix r enters resize mode. The status line shows RESIZE.

• h and l (or ← and →) move the focused pane’s nearest vertical border left or right, 4 columns at a time.
• k and j (or ↑ and ↓) move its nearest horizontal border up or down, 2 rows at a time.
• = equalizes.
• Esc or Enter leaves resize mode.

With the mouse

Drag the gap between two panes. You can also grab a pane’s frame edge that faces another pane: the right edge, the left edge, or the bottom edge. It works the same as dragging the gap.

Equalizing

prefix = (or Equalize sizes in the pane menu) gives the panes in each row and column an equal share of the space.

Sizes are kept as proportions, so when you resize the terminal window, the panes keep their shape.

Labeling a pane

prefix . opens the label pane dialog. The label replaces the pane’s automatic name everywhere: in its frame, the tab bar, the sidebar and the finder. Save an empty label to go back to the automatic one. You can also press r on an agent in the sidebar, or choose Label pane… in the pane menu.

Closing panes

prefix x closes the focused pane and stops its program. It doesn’t ask first, except when it’s the only pane left in wrkstrms: then it asks whether to quit. Close pane… in the pane menu, and x on an agent in the sidebar, ask first.

A pane also closes when its program exits. When a tab’s last pane closes, the tab closes; when a workspace’s last tab closes, the workspace closes. When the last pane in wrkstrms exits, wrkstrms exits.

Moving panes and tabs

A pane into a new tab

prefix ! (or Move to new tab in the pane menu) takes the focused pane out of its tab and puts it in a new tab of its own. The program keeps running. If it’s already the only pane in its tab, the top bar says already the only pane in this tab.

A pane into another tab

prefix M (or Move to another tab… in the pane menu) opens a menu titled Move <pane> to:

┌ Move keep the checkout form's values when a… to ──┐│ New tab C-Space ! ││───────────────────────────────────────────────────││ docs → right ││ docs ↓ below ││ billing › limits → right ││ billing › limits ↓ below │└───────────────────────────────────────────────────┘

• New tab does the same as prefix !.
• Each other tab is listed twice: → right puts the pane to the right of that tab’s focused pane, and ↓ below puts it below.
• Tabs in the current workspace come first. Tabs in other workspaces read Workspace › Tab. The menu lists up to 12 tabs.

wrkstrms then switches to the target tab and focuses the moved pane. If the pane was alone in its tab, the whole tab joins the target, and the empty tab goes away. If the target tab has no room, the top bar says not enough room in that tab.

Joining a tab into another

Joining takes a whole tab, with all its panes and their layout, and puts it into another tab as a split. There are three ways to do it.

From the tab you’re in: prefix @ (or Join another tab here… in the current tab’s menu) opens Join a tab beside <pane>. Pick a tab and a side, → right or ↓ below. That tab’s panes go beside your focused pane.

From the tab bar menu: right-click a tab that isn’t on screen and choose Join into current tab, right or Join into current tab, below. Its panes go beside the focused pane of the tab on screen.

By drag and drop: drag a tab from the tab bar and drop it onto a pane. The status line says drop on a pane to join the tab there (the side you drop on). The tab joins on the side of that pane nearest to where you let go:

╭──────────────────────╮
│         above        │
│ left            right│
│         below        │
╰──────────────────────╯

wrkstrms measures how close the drop point is to each of the four edges, relative to the pane’s width and height, and picks the closest. Drop near the left edge to join on the left, near the bottom to join below, and so on. Dropping the tab that’s already on screen does nothing (that's the tab on screen). Dropping a tab back on the tab bar just switches to it.

After a join:

• The source tab is gone. If it was the last tab in its workspace, that workspace goes away too.
• You switch to the joined tab, with the focus on the pane that was focused in the tab you moved. The top bar says, for example, joined tab "Checkout" to the right of this pane.
• If the target tab wasn’t a workstream, didn’t have a project, or didn’t have a Neovim, it takes those over from the tab that joined it.
• If there isn’t enough room, nothing changes and the top bar says not enough room to join <tab> here.

Tabs

Each workspace has one or more tabs. A tab holds a layout of panes.

To	Do
Open a new tab	prefix t, or click + in the tab bar
Open a workstream from a template as a tab	prefix n (see Workstreams)
Rename the current tab	prefix ,
Close the current tab	prefix & (asks first)
Go to tab 1 to 9	prefix 1…prefix 9, or Alt-1…Alt-9
Go to the previous or next tab	Alt-[ / Alt-] (wraps around)
Go back to the tab you were on before	prefix Tab
Switch with the mouse	Click the tab

New tabs

prefix t opens the new tab dialog. The field starts with the next tab number, such as 3. Press Enter to take it, or type a name. If you clear the field and save, the tab has no name and shows its focused pane’s label instead. The new tab runs your shell; in a workstream it starts in the workstream’s directory.

With the server running, ws <command> in any terminal also opens the command in a new tab. See Command reference.

Renaming tabs

prefix , opens rename tab with the current name. Save an empty name to go back to the automatic title (the focused pane’s label). You can also rename from the tab’s right-click menu, or with r on a tab row in the sidebar while filtering.

Closing tabs

prefix & asks Close this tab and its N panes?, then stops every pane in it. You go back to the tab you were on before. Closing the last tab of a workspace closes the workspace. Closing the last tab of the last workspace quits wrkstrms.

Workspaces

A workspace is a group of tabs, for example one product or one repo. The top bar shows the current workspace’s name, and the sidebar lists them all. wrkstrms starts with a workspace named after the directory you ran it in.

To	Do
Create a workspace	prefix W, + new in the sidebar, or New workspace… in a menu
Switch workspace	Click it in the sidebar, Enter on it in the sidebar, Alt-{ / Alt-}, or the finder
Rename a workspace	r on it in the sidebar, or Rename workspace… in its menu
Close a workspace	x on it in the sidebar, or Close workspace… in its menu (asks first)
Open a tab in another workspace	Right-click it in the sidebar and choose New tab here

A new workspace starts with one tab running your shell. If you leave the name empty, it’s called workspace N. Closing a workspace stops every pane in it. Closing the last workspace quits wrkstrms.

Jumping with the finder

prefix f or prefix w opens the finder. It lists every agent, tab, workspace, project, dev server port and command in one place.

1. Type a few letters. The letters must appear in order in the name, but not next to each other: dsys finds Design System. Case and spaces don’t matter.
2. Matches at the start of words, and runs of matching letters, rank higher. The name counts most, but the context counts too: rails pr finds the PR tab in the Rails workspace.
3. Press Enter to go there. For a command, Enter runs it.

With an empty query, the list starts with agents, most urgent first, then tabs, workspaces, projects, dev server ports (:3000 bin/rails server, going to the pane that runs it) and commands. From three letters on, matching memory items follow them.

To search only one kind of thing, start with its name: agent, tab, space, project, port, cmd (or > for commands) or mem. For example, tab zsh, port 3000, >split or mem setup_db.

Commands in the finder are the single-key prefix commands, listed by their names (split right, new tab, open PR) with their keys. See Keys and mouse for the finder’s keys.

Selecting and copying text

You can select text in a pane with the mouse, or with the keyboard in copy mode. Either way, wrkstrms copies it to your clipboard.

With the mouse

• Drag across text to select it. When you let go, wrkstrms copies it.
• Double-click a word to select and copy it. Paths and URLs count as one word, for example src/main.rs:42.
• Triple-click to select and copy the whole line.
• Hold Shift to select in programs that use the mouse themselves, such as nvim and lazygit. Without Shift, those programs get the clicks.
• Type or click anywhere to clear the selection.

The selection shows in reverse video. The mouse selects what’s on screen; to reach further back, use copy mode.

With the keyboard: copy mode

prefix [ puts a cursor in the focused pane. The status line shows COPY.

1. Move the cursor to where the text starts: h/j/k/l or the arrow keys, w and b by word, 0, ^ and $ within the line, Ctrl-u and Ctrl-d by half a screen, g and G to the top and bottom. Moving past the top or bottom of the screen scrolls the pane, back through its scrollback.
2. Press v to start selecting characters, or V for whole lines.
3. Move the cursor to where the text ends.
4. Press y (or Enter) to copy. Copy mode ends and the pane scrolls back to the bottom.

q or Esc leaves without copying. Every copy mode key is in Keys and mouse.

To find text before copying it, search instead: prefix / searches every pane’s scrollback, and picking a result opens copy mode with the cursor on the match, where n and N step through the other matches. See Search all panes.

Where the text goes

The top bar says how many characters were copied, such as copied 12 characters. Trailing spaces at the ends of lines are left out.

wrkstrms copies through your terminal with the OSC 52 escape sequence. This works in terminals that support OSC 52, such as Ghostty, iTerm2, kitty and WezTerm. If copying does nothing, check that your terminal allows OSC 52 clipboard access; see Troubleshooting.

How layouts are saved and restored

Your panes run in a background server. When you detach (prefix d) or close the terminal, every workspace, tab, layout and program keeps running as it was. Run ws to see it again.

The server also saves the layout to disk as it changes: workspaces, tabs, splits and their proportions, the focused and zoomed pane, and each pane’s command, directory and label. If the server stops without a clean quit, the next ws offers to restore it. A clean quit (prefix q or ws kill-server) clears the saved session. Sessions has the details, including how each kind of pane comes back.

See also

• The interface: every part of the screen
• Keys and mouse: the full key and mouse reference
• Workstreams: tabs opened from templates
• Scripting ws: building workspaces, tabs and splits from scripts