Skip to content

The interface

This page is a tour of the wrkstrms screen. It explains each part: what it shows, what its colors and glyphs mean, and what happens when you click it. For the full list of keys, see Keys and mouse. For working with splits, tabs and workspaces, see Panes, tabs and workspaces.

The screen at a glance

Section titled “The screen at a glance”

From top to bottom and left to right:

Part Where What it’s for
Top bar The first row, full width Where you are, messages, agent totals, and failing ws doctor checks
Sidebar The left column Workspaces, projects and every agent
Tab bar Two rows above the panes The current workspace’s tabs
Panes The main area Your programs, each in a framed pane
Status line The last row of the main column The mode, the branch and PR, and hints
Overlays On top of everything Popups, menus, the finder, the inspector and dialogs

The key shown as ⌃␣ on screen is Ctrl-Space, the prefix. The docs write it as prefix.

Status colors and glyphs

Section titled “Status colors and glyphs”

wrkstrms tracks the status of each AI agent (see Agents). The same glyph and color mean the same thing everywhere: in the top bar, the sidebar, the tab bar, pane frames, the finder and the inspector.

Glyph Color Status Meaning
● Red blocked The agent needs you: a permission prompt or a question
✓ Green done The agent finished a turn you haven’t looked at
◐ Yellow working The agent is running
○ Gray idle The agent finished and you’ve seen it, or it hasn’t started

A few more colors to know:

  • Teal is the accent. It marks the focused pane’s frame (when its agent has no other status), the active tab’s edge, the current workspace’s bar, and the NORMAL mode badge.
  • Purple is the wordmark, projects (◆), and the PREFIX mode badge.
  • Orange is used for messages in the top bar, the RESIZE and COPY mode badges, and the copy mode cursor.
  • Idle agents don’t color their tab, and a pane without an agent has a gray frame unless it’s focused.

When a tab or workspace holds several agents, it shows the most urgent status among them: blocked first, then done, working and idle.

Top bar

Section titled “Top bar”

The top bar is one row with three slots: left, center and right. Built-in items fill them today. The slots are there so plugins can add their own items later; plugins are not built yet.

Slot Item Shows
Left ▲ wrkstrms The wordmark
Left / storefront The current workspace’s name
Left ◆ Button a11y The project linked to the current tab, if any (see Projects)
Center Message Results and errors, in orange, for about four seconds (for example copied 12 characters or no agents need you)
Right ✗ doctor: 2 How many ws doctor checks fail, in red. Only shown when at least one fails; see The doctor badge
Right ● 1 need you ⌃␣ a A red pill with the number of blocked agents, and the key that jumps to the next one
Right ◐ 1 working How many agents are working
Right ✓ 3 done How many agents are done and not yet seen

Each item on the right appears only when its count is above zero. Idle agents are not counted here. When the window is too narrow, items drop off the end of each slot, the center slot first.

Two items on the right do something when you click them:

  • ● N need you jumps to the next agent that needs you, like prefix a.
  • ✗ doctor: N opens a tab named doctor that runs ws doctor and leaves a shell open after it.

Right-click the top bar for the general menu.

Pull request status is not in the top bar. It shows in the status line and on the tab chips in the sidebar.

The memory badge

Section titled “The memory badge”

When agents have proposed memory items that wait for your approval, the top bar shows ◇ N to approve. Click it to open the memory panel on its Proposed tab. It’s updated every 10 seconds. See Memory.

The doctor badge

Section titled “The doctor badge”

The server runs ws doctor --json in the background when it starts, and again every 30 minutes (not in a ws --local run). While any check fails (✗), the top bar shows ✗ doctor: N, where N is the number of failing checks. Warnings (!) don’t show a badge.

To see what’s wrong, click the badge, or choose Run ws doctor in the general menu. Both open the full report in a new doctor tab. After you open it, the server checks again about a minute later, so the badge goes away soon after you fix the problem. See Troubleshooting for every check.

Section titled “Sidebar”

The sidebar lists every workspace, your active projects, and every agent in every workspace. It is 30 columns wide, with a divider on its right.

The sidebar hides itself when the window is too narrow to keep at least 40 columns for the panes. prefix b shows it and moves the keyboard into it; pressed again from the sidebar, it hides the sidebar.

SPACES

Section titled “SPACES”

SPACES lists your workspaces. The number on the heading is how many there are.

  • The current workspace has a teal ▌ bar on its left and a lighter background. Under its name, its tabs appear as chips. Each chip shows the tab’s title, its agent status glyph (not for idle), and its PR number and checks when it has a pull request (#101 ✓ passing, #101 ✗ failing, #101 … running), then the first port something in the tab listens on (:3000, see dev servers). The chip for the active tab is bold. Chips wrap onto at most three lines.
  • Other workspaces show one dim line under their name: the active tab’s branch and PR badge for a workstream, or else the active tab’s title.
  • The count at the right of a workspace row, such as ●1, is its most urgent status and how many of its agents have that status. Workspaces whose agents are all idle show no count.

PROJECTS

Section titled “PROJECTS”

PROJECTS appears when you have active projects. Each row shows a purple ◆, the project’s name, and, at the right, the last agent to hand off. The second line is the next open task (next: …), or no open tasks. Press Enter on a project, or click it, to open it. See Projects.

AGENTS

Section titled “AGENTS”

AGENTS lists every agent in every workspace, most urgent first: blocked, then done, working and idle. Within each status, the agent that has held its status longest comes first.

  • The first line has the status glyph, the agent’s label, and at the right either an activity sparkline (for a working agent, showing how much output it produced recently) or the elapsed time it has been blocked or done (45s, 2m, 1h5m).
  • The second line is dim: the agent and model (claude·opus), then what it’s doing. That’s the question it’s asking when blocked, the current tool when working, or done, not seen. For an agent found by process name without status hooks, it says how to turn status on, such as no status: ws integrate claude (for Codex, no status: see ws doctor).
  • Blocked agents have a red-tinted background.
  • With no agents running, the section says none running.

Agents are never hidden by the filter.

Headings, folding and resizing

Section titled “Headings, folding and resizing”

Each section has a heading with a fold arrow: ▾ when open, ▸ when folded.

  • Click a heading to fold or unfold its section. From the keyboard, press z or Tab on any row in the section.
  • The ═ on the PROJECTS and AGENTS headings marks a drag handle. Drag the heading up or down to resize the section. A click without moving still folds it.
  • When you fold SPACES, AGENTS grows to fill the space.

Scrolling

Section titled “Scrolling”

Each section scrolls on its own. Turn the mouse wheel over a section to scroll it three lines at a time. When you move the selection with the keyboard, the section scrolls to keep the selected row in view.

Filter

Section titled “Filter”

Press / in the sidebar to filter. The SPACES heading turns into the filter line (/ your text).

  • Workspaces whose name matches stay, and each tab whose title matches is listed under its workspace, numbered (2 Invoice).
  • Projects whose name matches are listed under the spaces.
  • The AGENTS section is hidden while a filter is applied.
  • Matching ignores case.

With exactly one match, Enter jumps straight to it. See Keys and mouse for the rest.

Section titled “Footer”

The last row of the sidebar has two buttons:

Button Click to
+ new (left half) Open the new-workspace dialog
≡ menu (right half) Open the general menu

Using the sidebar from the keyboard

Section titled “Using the sidebar from the keyboard”

When the sidebar has the keyboard, the selected row is highlighted, the status line shows SIDEBAR, and keys like j/k, Enter, r and x act on the selected row. Esc or l goes back to the panes. See Keys and mouse for every key.

Tab bar

Section titled “Tab bar”

The tab bar has two rows above the panes. It shows the tabs of the current workspace.

  • The top row is a colored edge over each tab. It takes the color of the tab’s most urgent agent status (red, green or yellow). A tab without one has a teal edge when it’s active, and a gray edge otherwise.
  • The second row has the labels. The active tab is bold on a lighter block. A tab with a blocked, done or working agent shows its status glyph before the title.
  • A tab’s title is the name you gave it, or else the label of its focused pane (for example the agent’s label or the running command).
  • + at the end opens the new-tab dialog.

With the mouse:

Action Result
Click a tab (either row) Switch to it
Click + Open the new-tab dialog
Drag a tab onto a pane Join the whole tab into this one, beside that pane (see Panes, tabs and workspaces)
Right-click a tab Open the tab menu
Right-click empty space Open the general menu

Pane frames

Section titled “Pane frames”

Every pane has a rounded frame. The frame’s top border holds the pane’s title on the left and a detail on the right.

Frame color:

Frame When
Red The pane’s agent is blocked
Yellow The pane’s agent is working
Green The pane’s agent is done
Teal The pane is focused and its agent (if any) is idle
Gray Any other pane

Title: the status glyph (for agents), then the pane’s label. The label is, in order of preference: a label you set with prefix ., the agent’s label, the program’s terminal title, or the command. The title is bold in the frame color when the pane is focused or has an agent status, and dim otherwise. When a pane is zoomed, its title ends with [zoom].

Detail: for agents, the same text as the sidebar’s second line, such as claude · needs Bash. On narrow panes the detail is dropped first, then the title is cut short with ….

Ports: when the pane’s processes listen on TCP ports, the bottom border shows them on the right in blue, such as :3000 ↗. prefix o opens them, and prefix O lists every port in every workspace. See Dev servers and ports.

Selected text in a pane is shown in reverse video. In copy mode (prefix [), the cursor is an orange block, and after a search every match on screen is highlighted in the working color.

Right-click a pane’s top border for the pane menu. Right-clicks inside a pane go to its program.

Status line

Section titled “Status line”

The status line is the last row of the main column. It shows, from left to right:

  1. The mode badge, a colored block.
  2. The branch (⎇ ENG-2538/invoice) when the current tab is a workstream with a branch (see Workstreams).
  3. The PR and its checks (#101 CI ✓), when the branch has a pull request: CI ✓ passing (green), CI ✗ failing (red), CI … running (yellow).
  4. At the right: the current mode’s keys, then ⌃␣ ? keys · usage · settings. All three are links: click keys for the keys overlay (as prefix ?), usage for the usage dialog (as prefix U), or settings for Settings (as prefix S). When there isn’t room, the links go first, then the mode’s keys are cut short with ….
Mode Color When Hint at the right
NORMAL Teal Keys go to the focused pane (none)
PREFIX Purple You pressed Ctrl-Space a key for a command · ? all keys
RESIZE Orange Resize mode (prefix r) h/j/k/l move border · = equal · esc done
DIALOG Yellow A dialog asks for text or a yes or no (none)
SIDEBAR Blue The sidebar has the keyboard, or you’re typing a filter j/k move · enter go · / filter · z fold · i inspect · esc back
HELP Yellow The keys overlay is open (none)
MENU Blue A context menu is open j/k move · enter pick · esc close
FIND Blue The finder is open ↑↓ move · enter go · esc close
SEARCH Blue Searching every pane (prefix /) ↑↓ move · enter go to the line · esc close
INSPECT Blue The status inspector is open d/w/b/x set status · c copy report · esc close
MEMORY Blue The memory panel is open (prefix y) j/k move · tab tabs · / search · a approve · x reject/archive · esc close
GIT Blue The git panel is open (prefix g) j/k move · tab tabs · enter review/go · / filter · esc close
COPY Orange Copy mode (prefix [) hjkl move · v select · V lines · y copy · / search · q quit; after a search, n/N next/prev match · hjkl move · v select · y copy · q quit

While you drag a tab, the hint changes to drop on a pane to join the tab there (the side you drop on).

Overlays

Section titled “Overlays”

Which-key popup

Section titled “Which-key popup”

Off by default; turn it on with which_key = true under [leader] in keys.toml (Changing keys). With it on, after you press prefix, wait a moment (400 ms) and a popup titled after C-Space appears at the bottom right of the panes. It lists every prefix key in three columns: Panes; Tabs and Tools; Workspaces and General. Press a key to run its command, or Esc to cancel. If you know the key, press it right away and the popup never shows.

Keys overlay

Section titled “Keys overlay”

prefix ? opens wrkstrms keys, a centered cheat sheet with every prefix key by group, the Alt keys that work without the prefix (No prefix), the sidebar keys, the agent status glyphs, and the basic mouse actions. Press any key to close it.

Context menus

Section titled “Context menus”

Right-click shows a menu of what you can do with the thing under the pointer. Each item shows the key that does the same thing, when there is one (C-Space t, sidebar r, drag onto a pane).

Move with j/k, the arrow keys or the mouse; pick with Enter, Space or a click; close with Esc, q or a click outside. Items ending in … open a dialog or ask for confirmation. The menu for a tab or pane acts on that tab or pane: wrkstrms switches to it first, then runs the command.

Right-click on Menu
A workspace row in the sidebar Workspace menu
A tab in the tab bar Tab menu
A pane’s top border Pane menu
A project row in the sidebar Project menu
An agent row in the sidebar The pane menu for that agent’s pane
The top bar, empty tab bar or sidebar space, or ≡ menu General menu

prefix m opens the pane menu for the focused pane from the keyboard.

Workspace menu

Section titled “Workspace menu”
Item Keys
New tab here C-Space t
New workstream here… C-Space n
Rename workspace… sidebar r
Close workspace… sidebar x
New workspace… C-Space W
New project… C-Space N

Tab menu

Section titled “Tab menu”
Item Keys Notes
Split right C-Space v Splits that tab’s focused pane
Split below C-Space s
Editor (nvim) C-Space e
View Markdown… C-Space V
Inspect agent status C-Space I
Join into current tab, right drag onto a pane Only for a tab that isn’t on screen
Join into current tab, below drag onto a pane Only for a tab that isn’t on screen
Join another tab here… C-Space @ Only for the tab on screen
Post review… ws review --post Only for a review tab (Reviewing PRs)
Open PR C-Space p Only for a workstream tab with a branch
Done: close, remove worktree… ws done Only for a workstream tab with a branch; asks first. See ws done
Rename tab… C-Space ,
Close tab… C-Space &
New tab C-Space t
New workstream… C-Space n

Pane menu

Section titled “Pane menu”
Item Keys
Split right C-Space v
Split below C-Space s
Zoom C-Space z
Equalize sizes C-Space =
Label pane… C-Space .
Move to new tab C-Space !
Move to another tab… C-Space M
Inspect agent status C-Space I
View Markdown… C-Space V
Editor (nvim) C-Space e
Open http://localhost:3000 C-Space o; one per port the pane listens on, only when it listens on any
Close pane… C-Space x

Project menu

Section titled “Project menu”
Item Keys
Open workbench with Claude
Open files sidebar enter
Rename project… sidebar r
Archive (hide, keep files)
Delete project… sidebar x

General menu

Section titled “General menu”
Item Keys
New tab C-Space t
New workstream… C-Space n
New workspace… C-Space W
New project… C-Space N
Find… C-Space f
Dashboard C-Space D
Next agent needing you C-Space a
All keys C-Space ?
Run ws doctor
Detach (keep running) C-Space d
Quit wrkstrms… C-Space q

Tab pickers

Section titled “Tab pickers”

Two menus pick a tab rather than act on a place:

  • Move <pane> to (prefix M, or “Move to another tab…”) starts with New tab, then lists the other tabs.
  • Join a tab beside <pane> (prefix @, or “Join another tab here…”) lists the other tabs.

Each tab appears twice, as <tab> → right and <tab> ↓ below. Tabs in the current workspace come first; tabs in other workspaces read Workspace › Tab. The list shows up to 12 tabs. With no other tabs, the only item is No other tabs: New tab. See Panes, tabs and workspaces.

Finder

Section titled “Finder”

prefix f (or prefix w) opens the finder near the top of the screen: one fuzzy list of every agent, tab, workspace, project and command.

  • The first line is your query and the count of matches out of everything there is to find.
  • Each result shows a status glyph (or › for commands), its name with the matched letters highlighted, where it is (or, for a command, its group), and at the right its kind (agent, tab, space, project, port, mem) or, for a command, its key. A memory item shows its kind and scope where the others show where they are.
  • The selected result has a teal ▌.

With an empty query, agents come first, most urgent first. See Panes, tabs and workspaces for how matching works and Keys and mouse for its keys.

Status inspector

Section titled “Status inspector”

prefix I (or i on an agent in the sidebar, or “Inspect agent status” in a tab’s or pane’s menu) opens the inspector. It explains why an agent has the status it has.

The top part lists facts about the agent. Below the rule is a timeline of recent events. Each event has a kind: hook (an event the agent reported), status (a status change), detect (found by process name) or override (a status you set by hand). You can set the status by hand, copy a bug report, refresh, and scroll; see Keys and mouse and Agents.

Dialogs

Section titled “Dialogs”

Dialogs appear in the middle of the screen. There are two kinds: dialogs that ask for text, and confirmations.

Text dialogs have the buttons ↵ save, ^c clear and esc cancel. Confirmations have y yes and n no. The first button is the default. You can click the buttons. While a dialog is open, the rest of the screen ignores the mouse.

Dialog Opened by Hint shown
new tab prefix t, + in the tab bar (none); the field starts with the next tab number
rename tab prefix ,, tab menu, r in the sidebar (none)
new workspace prefix W, + new (none)
rename workspace Workspace menu, r in the sidebar (none)
label pane prefix ., pane menu, r on an agent in the sidebar empty goes back to automatic labels
new workstream prefix n template name [branch], or template #PR
new project prefix N its brief, plan and log open next, in this workspace
rename project Project menu, r in the sidebar its folder keeps its name; ws project rename --slug moves it
view markdown prefix V, tab or pane menu from this pane's directory; opens on the right

Confirmations ask, for example, Close this pane?, Close this tab and its 2 panes?, Close Design System and its 5 panes? or Quit wrkstrms and stop 9 panes?.

See also

Section titled “See also”