The wrkstrms guide
wrkstrms is a terminal environment for running many AI coding agents side by
side. You start it with the ws command, and it holds your agents, editors
and shells in workspaces of tabs and split panes, all in a background server
that keeps running when you close the terminal. It tracks what each agent is
doing and shows you, at a glance, which one needs you next.
This guide is for developers who run several agents at once, such as Claude Code and Codex, and want one place to watch them, switch between them, and pick up their work later. It assumes you are at home in a terminal and with git. If you have used tmux, much of it will feel familiar.
The prefix key is Ctrl-Space. In this guide, prefix v means press
Ctrl-Space, let go, then press v.
Start here
Section titled “Start here”Read these four pages in order:
- Getting started: install
ws, connect your agents, and take a five-minute tour. - Concepts: how the server, workspaces, tabs, panes, workstreams, agents and projects fit together.
- The interface: what each part of the screen shows.
- Keys and mouse: every key binding and mouse action.
All pages
Section titled “All pages”Getting going
Section titled “Getting going”| Page | What it covers |
|---|---|
| Getting started | Install, agent hooks, ws doctor, a first tour, and the Dashboard |
| Concepts | The pieces of wrkstrms and how they fit together |
| The interface | The top bar, sidebar, tab bar, pane frames, status line, menus and dialogs |
| Keys and mouse | Every prefix key, Alt key, mode key and mouse action |
Everyday use
Section titled “Everyday use”| Page | What it covers |
|---|---|
| Panes, tabs and workspaces | Splitting, moving, resizing, the finder, and copying text |
| Agents | Agent status, hooks, labels, notifications and the status inspector |
| Workstreams | Worktrees and branches from templates, Neovim per tab, and PR status |
| Projects | Goals, plans and handoffs that carry work across agent sessions |
| Sessions | The background server, attach and detach, named servers, and restore after a crash |
| Markdown viewer | Reading live-updating Markdown with ws view |
| Settings | The Settings workspace (prefix S): a page per area of settings, saved to your config files |
| Changing keys | keys.toml: your own leader (prefix), rebinding, sequences and direct keys; the ws keys editor |
| Memory | One SQLite memory every agent shares: ws mem add, search, list, edit, forget |
| AI usage | Tokens by agent and model, Codex’s rate limit, and the commands, skills and tools agents used: ws usage |
| Reviewing PRs | ws review and prefix R: a worktree, the PR’s discussion and your review agent, one tab per PR |
| Dev servers and ports | Seeing which ports each pane’s servers listen on, opening them with prefix o, and listing every one with prefix O |
Automation
Section titled “Automation”| Page | What it covers |
|---|---|
| Scripting ws | Building workspaces, tabs and splits from shell scripts |
| Protocol | The socket protocol, for writing your own clients and tools |
Reference
Section titled “Reference”| Page | What it covers |
|---|---|
| Command reference | Every ws command, argument and flag |
| Configuration | Environment variables, files and directories, and the template format |
| Troubleshooting | ws doctor, logs, and fixes for common problems |