blog

~ ❯ cat blog/getting-around.md

Getting around a dozen agents

· opcodezero

A few agents means a few workspaces, several tabs each, and panes inside those: agents, editors, dev servers, test watchers. The question stops being “which window” and becomes “where was that?” wrkstrms has three answers, depending on what you know.

You know its name: the finder

⌃␣ f opens the finder. It lists every agent, tab, workspace, project and command in one place, and a few letters narrow it down. The letters only have to appear in order, so dsys finds Design System, and matches at the start of words rank higher.

⌃␣ f, then check: the blocked agent and the finished one.

With an empty query, agents come first, most urgent first, so ⌃␣ f then Enter is another way to get to the agent that needs you. To look at one kind of thing, start with its name: agent, tab, space, project, mem or > for commands. >split finds the split commands and runs one with Enter, and from three letters on, matching memories show up too.

You know what it said: search all panes

Sometimes you don’t remember where something is, only what it printed: a failing test, an error, a port. ⌃␣ / searches the text of every pane in every workspace, scrollback included.

⌃␣ /, then fail: the test watcher's failure and the agent talking about it, side by side.

It’s plain text with smart case: error finds Error and ERROR, Error finds only Error. Start with \v for a regular expression (\vport \d+). Tab narrows it to this workspace, then this tab. Enter goes to that pane and puts the cursor on the match, in copy mode.

You don’t know the key: ask

Every command in wrkstrms is the prefix, ⌃␣ (Ctrl-Space), then one key. You don’t need to learn them up front.

⌃␣ ? shows every key on one screen: the prefix keys by group, the keys that work without the prefix, the sidebar’s keys, and what the status glyphs mean.

If you’d rather be reminded as you go, turn on the which-key popup (which_key = true under [leader] in keys.toml, or in Settings). Press the prefix, pause a moment, and it lists what comes next. If you already know the key, press it right away and the popup never shows.

Keys without the prefix

A handful of moves are frequent enough to skip the prefix:

Key Does
Alt-a Jump to the next agent that needs you
Alt-h/j/k/l Focus the pane to the left, below, above, right
Alt-1…Alt-9 Go to a tab
Alt-[ / Alt-] Previous or next tab
Alt-{ / Alt-} Previous or next workspace

Your keys, not ours

The prefix itself can change: a backtick, tmux’s Ctrl-a, Option-Space, or a spare key like F12. Any command can be rebound, keys can lead to other keys (⌃␣ o p to open a PR), and ws keys opens an editor with a map of your keyboard showing what every key does. The same editor is the first page of Settings (⌃␣ S), where changes save as you make them.

The Keys and mouse guide lists everything, and Changing keys covers the rest.