Getting started

This page takes you from a fresh checkout to a running wrkstrms session. You build and install the ws command, connect it to your agent CLIs so it can show their status, check your setup with ws doctor, and then take a short tour: a workspace, a split, a second tab, the finder, and detaching and reattaching.

Requirements

Need	Notes
macOS or Linux	ws uses Unix sockets and PTYs. Windows isn’t supported.
Rust	Install it with rustup. The repo pins its toolchain in rust-toolchain.toml, and rustup installs that version for you on the first build. The minimum supported version is 1.90.
Zig 0.15.2 exactly	Used to build Ghostty’s libghostty-vt, the terminal emulator inside each pane. Ghostty’s build rejects Zig 0.16.
git 2.17 or newer	Needed for workstreams (git worktrees).

Optional tools that ws works with:

Tool	Used for
claude (Claude Code), codex (Codex)	The agents whose status ws tracks.
nvim 0.10 or newer	The per-tab editor (prefix e, ws open) and project files.
gh, logged in	Pull request status in the status line and sidebar, and ws new --pr.
lazygit	Runs well in a pane; ws doctor checks for it.

Installing Zig 0.15.2

On macOS, Homebrew’s zig formula is now 0.16, so install the versioned formula and put it first on your PATH:

brew install zig@0.15

export PATH="$(brew --prefix zig@0.15)/bin:$PATH"

On Linux, download 0.15.2 from ziglang.org and put its directory on your PATH.

Check the version before you build:

zig version

Build and install

From the root of the repository:

cargo install --path crates/ws

This builds ws and copies it to ~/.cargo/bin/ws. The first build compiles Ghostty and takes about a minute. Make sure ~/.cargo/bin is on your PATH, then check the install:

ws --version

To upgrade later, pull the new code and run the same cargo install command again. A server that is already running keeps using the old build; see Sessions for how to switch.

Install the agent hooks

Agents tell ws what they are doing through hooks: small commands the agent CLI runs at points in its lifecycle (a prompt was sent, a tool is running, the turn finished, it needs permission). Install them once for each agent CLI you use.

For Claude Code:

ws integrate claude

This adds hooks to ~/.claude/settings.json and keeps a backup of the old file next to it.

For Codex:

ws integrate codex

This adds hooks to ~/.codex/hooks.json (or $CODEX_HOME/hooks.json). Codex only runs hooks when its hooks feature is on. The feature is on by default in current Codex. ws integrate codex asks codex features list, and if the feature is off, or Codex can’t say, it sets features.hooks = true in ~/.codex/config.toml. It also sets features.daemon_auto_start = false: Codex’s shared background daemon would run the hooks for every Codex window as if they came from one pane. It keeps the rest of that file as it was, and keeps a backup. If the daemon is already running, it tells you how to stop it.

A few things to know:

• Restart running agents. Agents that were already running pick up the hooks only after a restart.
• Hooks are harmless outside ws. Each hook runs ws report --agent <kind> <event>. Outside a ws pane, that command does nothing and always exits 0.
• Hooks point at one binary. By default they run the ws you ran integrate from. Run ws integrate from the installed ws (in ~/.cargo/bin), not from a build in target/. To choose another binary, pass --bin /path/to/ws.
• See before you write. --print shows the resulting file without writing it.
• Undo. ws integrate claude --remove (or codex --remove) takes the hooks out again. For Codex, --remove leaves the features settings alone, since other hooks may rely on them.

Without hooks, ws still finds agent CLIs by their process name and lists them with “no status”. See Agents for how status works.

Check your setup

ws doctor

ws doctor checks your tools, the agent hooks, your workstream templates, the terminal, and ws’s own state. Each problem comes with the command that fixes it. It exits with code 1 if something is broken, and 0 if there are only warnings.

ws doctor --fix

With --fix, ws doctor first offers to apply the safe fixes: it removes sockets left behind by crashed runs and creates ws’s state directory. It asks before it changes anything. Troubleshooting lists every check.

You don’t have to remember to run it. While ws runs, its server runs ws doctor in the background at start and every 30 minutes, and shows ✗ doctor: N in the top bar when a check fails. Click the badge to see the report.

A five-minute tour

The prefix key is Ctrl-Space. In this guide, prefix s means: press Ctrl-Space, let go, then press s. If you pause after the prefix, a popup lists what you can press next.

On macOS, keys with Alt need your terminal to send Option as Alt. In Ghostty, set macos-option-as-alt = true.

1. Start ws

Go to a project directory and start ws:

cd ~/code/my-app

ws

ws starts a background server and attaches your terminal to it. You see one workspace, named after the directory (my-app), with one tab running your shell. The sidebar on the left lists workspaces and agents. The top bar shows agent totals, and the status line at the bottom shows the current mode and its keys.

You can also start ws with a command instead of a shell:

ws claude --model opus

Everything after the program name is passed to it.

2. Split the pane

• prefix v splits the focused pane to the right and opens a shell there.
• prefix s splits it below.
• Alt-h/j/k/l moves focus left, down, up or right. You can also click a pane.
• prefix z zooms the focused pane to fill the tab; press it again to unzoom.
• prefix x closes the focused pane.

Start an agent in one of the panes, for example claude. Once its hooks report, its status shows on the pane’s frame, its tab, and the Agents section of the sidebar.

3. Open a second tab

• prefix t opens the new-tab dialog. Press Enter to take the suggested name.
• Alt-1 to Alt-9 (or prefix 1 to 9) go to a tab by number.
• prefix Tab goes back to the last tab.

From another terminal, ws <command> opens the command in a new tab of the running server, in the directory you ran it from:

ws codex

4. Find anything

prefix f opens the finder: one fuzzy list of every agent, tab, workspace, project and command. Type a few letters, then press Enter to jump there or run the command. With an empty query, the list starts with the agents, most urgent first.

prefix a (or Alt-a) jumps straight to the next agent that needs you.

5. Detach and reattach

Press prefix d to detach. Your terminal goes back to its shell and prints this line:

[detached; `ws` reattaches]

The server and every program in it keep running. Closing the terminal window does the same thing.

Run ws again, from any terminal, to reattach to the same screen:

ws

prefix q is different: it quits the server and stops every pane and everything running in them. It asks first.

6. Learn the keys

prefix ? shows the whole keymap. Right-click a workspace, tab, pane header or empty space for a menu of what you can do there, with the keys that do it.

The Dashboard

The first thing you see is the Dashboard, the first workspace of a fresh start. Its page keeps up with what you’re doing:

• Now: agents that need you or are working (with what they’re doing and for how long), your open workstreams with their PR status, and how many PRs wait for your review. Each is a button: an agent or workstream takes you to its pane, and the review count opens the git panel.
• Your leader key, at the top, with a link to Settings (“Change your keys and more in Settings”: click it, or Tab to it and Enter).
• Get started and Moving around: your leader key and the keys that matter, read from your own keys.toml, so rebinding shows.
• Agents: the status colors, and whether each agent CLI’s status hooks are installed (with the command that installs them if not).
• Reviews and memory, and Health: what ws doctor found, with fixes.
• Buttons to start a tab, workstream or project, review PRs, open the git panel, see every key or open Settings, and your workspaces and projects.

Its pane’s frame is titled “Dashboard”. It’s never listed under AGENTS.

A fresh start (ws with no server running and nothing to restore) opens the Dashboard as the first workspace and shows it. It’s a workspace like any other: close it if you don’t want it, and bring it back any time with prefix D, “Dashboard” in the main menu, or ws dashboard in a pane. A restore brings back what you had, with or without it. To stop fresh starts opening it, set this in ~/.config/ws/config.toml (prefix D still works):

[dashboard]
enabled = false

Where to go next

• Concepts: how servers, workspaces, tabs, panes, workstreams, agents and projects fit together.
• Keys: every key binding.
• Agents: agent status, the inspector, and notifications.
• Workstreams: worktrees and branches from templates.
• Projects: goals and handoffs that outlive agent sessions.
• Sessions: the background server, detach, and restore after a crash.
• Troubleshooting: when something doesn’t work.