Keys and mouse

This page lists every key and mouse action in wrkstrms, as they are by default. To change them, including the prefix (the leader), see Changing keys. Most commands start with the prefix, Ctrl-Space: press it, let go, then press the command key. A few Alt keys work without the prefix. Some screens, such as the sidebar, the finder and dialogs, have keys of their own. For what each part of the screen is, see The interface.

How the prefix works

Press Ctrl-Space. The status line shows PREFIX.
Press a command key, such as v to split right. The docs write this as prefix v.
The status line’s right end reminds you: a key for a command · ? all keys. prefix ? lists every key. If you’d like a popup of them whenever you pause after the prefix, turn on which_key in Changing keys.
Esc cancels. A key with no command shows no command on C-Space <key> in the top bar.
If you’ve set up sequences in keys.toml, a key can lead to another key (prefix o p). While it waits, the status line shows PREFIX o and what can follow (p open PR · d open dev server · esc cancel). See Changing keys.
prefix ? opens the full keymap on screen, in as many columns as your screen fits. Any key closes it. If the screen is too small to show it all, j/k (or the arrows, PageUp/PageDown, g/G) scroll it and the bottom border says ↓ more. e opens the shortcut editor in a new tab (Changing keys).
To send Ctrl-Space itself to the program in the pane, press it twice: prefix Ctrl-Space.

Every other key goes to the program in the focused pane.

On screen, menus write the prefix as C-Space and the top bar and finder write it as ⌃␣. They all mean Ctrl-Space.

Prefix keys

Press these after Ctrl-Space. The Keys column shows the key; the Action column shows the name the which-key popup and prefix ? use for it.

Panes

Keys	Action
`s`	split below
`v`	split right
`h/j/k/l`	focus pane
`H/J/K/L`	swap pane
`z`	zoom
`r`	resize mode
`=`	equalize
`x`	close pane
`.`	label pane
`!`	pane to new tab
`[`	copy mode
`M`	pane to another tab
`;`	previous pane

s and v open a shell in the new pane and focus it. In a workstream tab, the shell starts in the workstream’s directory.
h/j/k/l move focus left, down, up or right. Moving left from the leftmost pane moves into the sidebar, when it’s shown.
H/J/K/L swap the focused pane with its neighbor in that direction. Focus stays with the pane you moved.
z fills the tab with the focused pane, or puts it back. Moving focus to another pane ends the zoom.
r enters resize mode.
= gives the panes in each row and column equal space.
x closes the focused pane right away and stops its program. If it’s the only pane left in wrkstrms, it asks whether to quit instead.
. opens the label pane dialog. An empty label goes back to the automatic one.
! moves the focused pane into a new tab of its own.
[ enters copy mode on the focused pane, to select and copy text with the keyboard.
M opens a menu of tabs to move the focused pane into.
; goes back to the pane that was focused before.

Tabs

Keys	Action
`@`	join a tab here
`t`	new tab
`n`	new workstream
`,`	rename tab
`&`	close tab
`Tab`	last tab
`1-9`	go to tab

@ opens a menu of other tabs to join into this one, beside the focused pane.
t opens the new tab dialog. It suggests the next tab number as the name; Enter takes it. Clear it to have the tab show its command instead.
n opens the new workstream dialog: template name [branch], or template #PR. See Workstreams.
, renames the current tab. An empty name goes back to the automatic one.
& closes the current tab and every pane in it. It asks first.
Tab switches to the tab you were on before.
1-9 go to tab 1 to 9 in the current workspace.

Workspaces

Keys	Action
`b`	sidebar
`f/w`	find anything
`/`	search all panes
`W`	new workspace
`N`	new project

b shows the sidebar if it’s hidden and moves the keyboard into it. From the sidebar, prefix b hides it.
f and w both open the finder.
/ searches the text of every pane, scrollback included. See Search all panes.
W asks for a name and opens a new workspace with a shell. An empty name gives workspace N.
N asks for a name and creates a project. See Projects.

Tools

Keys	Action
`V`	view markdown
`e`	editor (nvim)
`p`	open PR
`A`	continue in another agent
`y`	memory
`c`	review changes
`g`	git panel
`R`	review PRs
`o`	open dev server
`O`	all dev servers

V asks for a Markdown file, relative to the focused pane’s directory, and opens it in a viewer on the right. See Markdown viewer.
e focuses the tab’s Neovim, or starts one in a split if there isn’t one.
p opens the workstream’s pull request in your browser.
R asks for pull requests (URLs, alias/N, org/repo#N or numbers) and opens a review tab for each, with your review agent started. See Reviewing PRs.
c reviews this tab’s changes: the git panel’s This branch, where Enter diffs a file in Neovim and s sends your :WsComment comments to the agent. See Reviewing PRs.
g opens the git panel: PRs waiting for your review, your review tabs, your own PRs, and this tab’s branch. See below and Reviewing PRs.
o opens the dev server running in the focused pane (or tab) in your browser; with several, a menu picks one. See Dev servers and ports.
O lists every dev server in every workspace: its port, where it is and its command. Enter goes to its pane and o opens it in the browser. See below.

General

Keys	Action
`a`	next needing you
`D`	dashboard
`S`	settings
`I`	inspect agent status
`m`	menu for this pane
`?`	all keys
`d`	detach
`q`	quit (stops every pane)
`C-Space`	send C-Space

a jumps to the next agent that is blocked or done. Press it again for the one after. See Agents.
D goes to the Dashboard, opening it again as the first workspace if you closed it.
S opens Settings, a workspace of settings pages (making it the first time).
I opens the status inspector for the focused pane.
m opens the focused pane’s context menu, as a right-click on its top border would.
? opens the keys overlay.
d detaches: this terminal closes and every pane keeps running in the server. Run ws to come back. See Sessions.
q asks, then stops every pane and the server.
C-Space (that is, prefix Ctrl-Space) sends a literal Ctrl-Space to the focused pane.

Keys without the prefix

These Alt keys work at any time in normal mode, and from the sidebar.

Keys	Action
`Alt-a`	next needing you
`Alt-h/j/k/l`	focus pane
`Alt-1…9`	go to tab
`Alt-[ / Alt-]`	previous / next tab
`Alt-{ / Alt-}`	previous / next workspace

Alt-h from the leftmost pane moves into the sidebar.
Alt-[ and Alt-] wrap around at the ends; so do Alt-{ and Alt-}.
From the sidebar, an Alt key leaves the sidebar and then runs. Alt-l just goes back to the panes.

Your terminal must send Alt as a modifier (on macOS, “Option as Meta” or the equivalent) for these to work.

Mode keys

Copy mode

prefix [ puts a cursor in the focused pane so you can select and copy text with the keyboard, back through the pane’s scrollback. The status line shows COPY and the hint hjkl move · v select · V lines · y copy · / search · q quit.

The cursor starts where the program’s cursor is (or on the bottom row) and is drawn as an orange block. The selection is shown in reverse video. When the cursor moves above or below the screen, the pane scrolls with it, so a selection can cover more than one screen. Each pane keeps about 10 MB of scrollback: roughly 5,500 lines at 200 columns, 19,000 at 60.

Keys	Action
`h` / `←`	Left
`l` / `→`	Right
`k` / `↑`	Up a line
`j` / `↓`	Down a line
`w`	Next word
`b`	Previous word
`0`	Start of the line
`^`	First non-blank character of the line
`$`	Last non-blank character of the line
`g` / `Home`	Top of the scrollback
`G` / `End`	Bottom
`Ctrl-u` / `Ctrl-d`	Up / down half a screen
`Ctrl-b` / `PageUp`	Up a screen
`Ctrl-f` / `PageDown`	Down a screen
`v` / `Space`	Start selecting characters, or stop
`V`	Start selecting whole lines, or stop
`y` / `Enter`	Copy the selection and leave copy mode
`q` / `Esc` / `Ctrl-c`	Leave without copying
`/`	Leave copy mode and search all panes
`n` / `N`	Next / previous match of the search that opened copy mode

Copying uses OSC 52, as mouse selection does, and the top bar says copied N characters. With nothing selected, y stays in copy mode and says nothing selected: v starts a selection, V selects lines. Trailing spaces at the ends of lines are left out. Leaving copy mode, either way, scrolls the pane back to the bottom.

Other keys do nothing in copy mode. The prefix doesn’t work there either (Ctrl-Space acts like Space), so leave copy mode before you run a prefix command.

The sidebar has the keyboard after prefix b, prefix h or Alt-h from the leftmost pane. The status line shows SIDEBAR.

Keys	Action
`j` / `↓`	Move down
`k` / `↑`	Move up
`gg`	Go to the top
`G`	Go to the bottom
`Enter`	Jump to the selected workspace, tab or agent; open the selected project
`/`	Start a filter
`z` / `Tab`	Fold or unfold the selected row’s section
`i`	Inspect the selected agent’s status (agents only)
`r`	Rename the selected workspace, tab or project, or label the selected agent’s pane
`x`	Close the selected workspace, tab or agent’s pane, or delete the selected project (asks first)
`Esc`	Clear the filter if there is one; otherwise go back to the panes
`l` / `→`	Go back to the panes
`prefix` + key	Prefix commands work here too
Alt keys	Leave the sidebar and run the command

While you type a filter (after / in the sidebar):

Keys	Action
Letters	Add to the filter; the selection moves to the first match
`Backspace`	Delete a character
`Ctrl-u` / `Ctrl-c`	Clear the filter
`Ctrl-w`	Delete the last word
`↓` / `↑`	Move the selection
`Enter`	With exactly one match, jump to it; otherwise select the first match and go back to sidebar keys, keeping the filter
`Esc`	Clear the filter and go back to sidebar keys

Pasting into the filter takes the first line of the pasted text.

Resize mode

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

Keys	Action
`h` / `←`	Move the nearest vertical border left (4 columns)
`l` / `→`	Move the nearest vertical border right (4 columns)
`k` / `↑`	Move the nearest horizontal border up (2 rows)
`j` / `↓`	Move the nearest horizontal border down (2 rows)
`=`	Equalize
`Esc` / `Enter`	Leave resize mode

Other keys do nothing in resize mode.

Dialogs

Text dialogs (new tab, rename, label, new workspace, new project, new workstream, view markdown):

Keys	Action
`Enter`	Save
`Esc`	Cancel
`Ctrl-c` / `Ctrl-u`	Clear the field
`Ctrl-w`	Delete the last word
`Backspace`	Delete a character

Text is limited to 40 characters. Pasting takes the first line of the pasted text. You can also click the ↵ save, ^c clear and esc cancel buttons.

Confirmations (close, quit, delete):

Keys	Action
`y` / `Y`	Yes
Any other key	No

You can also click y yes or n no.

Menus

While a context menu or tab picker is open (status line MENU):

Keys	Action
`j` / `↓` / `Tab`	Next item (wraps around)
`k` / `↑` / `Shift-Tab`	Previous item (wraps around)
`Enter` / `Space`	Choose the item
`Esc` / `q`	Close the menu

Finder

While the finder is open (status line FIND):

Keys	Action
Letters	Type the query; the selection goes back to the top
`↓` / `Tab` / `Ctrl-n` / `Ctrl-j`	Next result
`↑` / `Shift-Tab` / `Ctrl-p` / `Ctrl-k`	Previous result
`Enter`	Go to the result, or run the command
`Esc`	Close
`prefix`	Close
`Backspace`	Delete a character
`Ctrl-u` / `Ctrl-c`	Clear the query
`Ctrl-w`	Delete the last word

Start the query with a kind word to search only that kind:

Start with	Finds
`agent` or `agents`	Agents
`tab` or `tabs`	Tabs
`space` or `spaces`	Workspaces
`project` or `projects`	Projects
`port` or `ports`	Dev servers: listening ports, by number and command
`cmd` , `command` , `commands` or `>`	Commands
`mem` , `memory` or `memories`	Memory items (`mem` alone: the newest)

For example, tab zsh, agents, port 3000, >split, or mem setup_db.

Search all panes

prefix / (or / in copy mode) searches the text of every pane in every workspace, scrollback included. It opens in the finder’s frame, titled search all panes, with the status line SEARCH.

ws reads every pane’s text once, when the search opens; typing then filters it. Output that arrives while the search is open isn’t included until you search again. A pane that takes more than half a second to answer is left out.
The query is plain text, not fuzzy. It ignores case unless it has an uppercase letter (Vim’s smart case): error finds Error and ERROR, Error finds only Error.
Start the query with \v to make the rest a regular expression (Rust regex syntax), with the same smart case: \vport \d+, \v(panic|FAIL). While the pattern is invalid, the list shows bad regex: … instead of results.
Tab narrows where it looks: all panes, then this workspace, then this tab, then all panes again. The title says which (search all panes, search this workspace, search this tab) and the count covers only those panes. (In the ordinary finder Tab moves down; in a search, use ↓ or Ctrl-n.)
Each result is one matching line, with where it is (workspace › tab · pane). The focused pane comes first, then the rest of the current workspace, then the other workspaces. Within a pane, the newest lines come first. At most 200 lines are listed; the count shows 200+ when there are more.
A long line is cut so the match shows: leading spaces are dropped, and the start becomes … when the match is far along.

The other keys are the finder’s: type to search, ↑/↓ to move, Esc or the prefix to close. Enter (or a click) goes to the result’s pane and opens copy mode with the cursor on the match, scrolled so the line is in the middle. Every match of the query on screen is highlighted, and the status line hint becomes n/N next/prev match · hjkl move · v select · y copy · q quit:

Keys	Action
`n`	Next match in this pane, reading downward
`N`	Previous match

n and N read the pane’s text again, so they find output that arrived after the search. Going past the last match wraps to the first, and the top bar says search wrapped to the top (or to the bottom for N). Copy mode works as usual from there: v at the match, move, and y copies.

In a full-screen program (Neovim, an agent’s full-screen view) there’s no scrollback, so only what’s on screen is searched.

Memory panel

prefix y opens the memory panel (status line MEMORY):

Keys	Action
`Tab` / `Shift-Tab`, `l` / `h`, `1`–`7`	Switch tabs: Here, Proposed, Repo, Project, Global, All, Sessions
`j` / `k`, `g` / `G`	Move
`/`	Search (Enter or Esc stops typing)
`a`	Approve a proposed item
`x`	Reject a proposed item, or archive an active one
`p`	Pin or unpin
`e`	Edit it in Neovim, in its own tab
`D` `D`	Delete it for good (press twice)
`r`	Reload
`Esc` / `q`	Clear the search, then close

Git panel

prefix g opens the git panel (status line GIT):

Keys	Action
`Tab` / `Shift-Tab`, `l` / `h`, `1`–`4`	Switch tabs: Review requests, Reviews, My PRs, This branch
`j` / `k`, `g` / `G`	Move
`Enter`	Review the PR; go to the review or workstream tab; open the file
`space`, `R`	Mark review requests; review the marked ones
`P`, `u`, `d`	On a review tab: post, update (fresh review), done
`C`	On My PRs: send its unresolved review comments to the agent on its branch
`p`, `c`, `f`	On This branch: open its PR, create one, fetch
`Enter`, `a`, `s`, `e`	On This branch: diff a file, diff them all, send your comments, open the file
`o`, `y`	Open the PR in the browser; copy its link
`/`	Filter (Enter or Esc stops typing)
`r`	Refresh
`Esc` / `q`	Clear the filter, then close

Dev servers list

While the dev servers list is open (prefix O, status line PORTS):

Keys	Action
`j` / `↓`	Next port
`k` / `↑`	Previous port
`g` / `Home`	First port
`G` / `End`	Last port
`Enter`	Go to the port’s pane
`o`	Open it in the browser (the list stays open)
`Esc` / `q`	Close

See Dev servers and ports.

Status inspector

While the inspector is open (status line INSPECT):

Keys	Action
`d`	Set the status to done
`w`	Set the status to working
`b`	Set the status to blocked
`x`	Set the status to idle
`c`	Copy a bug report to the clipboard and save it to a file
`r`	Refresh
`j` / `↓`	Scroll the timeline down
`k` / `↑`	Scroll the timeline up
`Esc` / `q` / `i`	Close

A status you set by hand lasts until the agent’s next real event. See Agents.

Keys overlay and which-key

Screen	Keys
Keys overlay (`prefix ?`)	`j`/`k` scroll when it doesn’t fit; any other key closes it
Which-key popup (when turned on)	Press a prefix key to run it, or `Esc` to cancel

Markdown viewer

These keys work in ws view (and prefix V). See Markdown viewer.

Keys	Action
`j` / `↓`	Scroll down a line
`k` / `↑`	Scroll up a line
`d`	Down half a page
`u`	Up half a page
`Space` / `f` / `PageDown`	Down a page
`b` / `PageUp`	Up a page
`g` / `Home`	Go to the top
`G` / `End`	Go to the bottom
`]`	Next heading
`[`	Previous heading
`/`	Search: type, then `Enter` to find, or `Esc` to cancel
`n`	Next match
`N`	Previous match
`r`	Reload the file
`q` / `Esc` / `Ctrl-c`	Close the viewer
Mouse wheel	Scroll three lines

Mouse

Clicking

Where	Action
A pane	Focus it (the click also goes to the program if it uses the mouse)
A tab (either row of the tab bar)	Switch to it
`+` in the tab bar	Open the new-tab dialog
`● N need you` in the top bar	Jump to the next agent that needs you
`✗ doctor: N` in the top bar	Open a tab with the `ws doctor` report
A sidebar row	Jump to that workspace, tab or agent, or open that project
The SPACES heading	Fold or unfold SPACES
The PROJECTS or AGENTS heading	Fold or unfold it (click without dragging)
`+ new` in the sidebar footer	Open the new-workspace dialog
`≡ menu` in the sidebar footer	Open the general menu
A dialog button	Press it
A menu item	Choose it
Outside an open menu or the finder	Close it
A finder result	Go to it
A row in the dev servers list	Go to its pane (outside the list closes it)

Right-click menus

Right-click on	Opens
A workspace row in the sidebar	The workspace menu
A tab	The tab menu
A pane’s top border	The pane menu
An agent row in the sidebar	The pane menu for that agent
A project row in the sidebar	The project menu
The top bar or empty space in the tab bar or sidebar	The general menu
Inside a pane	Nothing: the right-click goes to the program

Moving the mouse over a menu highlights the item under it. The menus are listed in The interface.

Dragging

Drag	Action
The gap between two panes	Resize them
A pane’s frame edge that faces another pane	Resize, as if you dragged the gap
A tab onto a pane	Join the whole tab into the current one, on the side of the pane nearest to where you drop it
A tab back onto the tab bar	Switch to it
The PROJECTS or AGENTS heading (`═`)	Resize that sidebar section
Across text in a pane	Select text; letting go copies it

When you drop the tab that’s already on screen onto one of its own panes, nothing moves and the top bar says that's the tab on screen.

Selecting text

Action	Result
Drag across text	Select it; letting go copies it to the clipboard
Double-click	Select and copy a word (paths and URLs count as one word)
Triple-click	Select and copy the whole line
`Shift` + drag or click	Select even in programs that use the mouse, such as nvim and lazygit
Type or click	Clear the selection

In programs that use the mouse themselves, a plain drag goes to the program. Copying uses OSC 52, so it goes through your terminal. The top bar says how many characters were copied. To select with the keyboard, or text that has scrolled off the screen, use copy mode. See Panes, tabs and workspaces.

The wheel

Over	Action
A sidebar section	Scroll that section three lines
A pane whose program uses the mouse	The program gets the wheel
A full-screen program that asks for the wheel as arrow keys (such as `less`)	It gets arrow keys
Any other pane	Scroll its scrollback three lines
The finder	Move the selection

The wheel scrolls whatever is under the pointer, whether it’s focused or not.