README
¶
rook
A rebuild from an empty Go module, around open-source tooling instead of
under it. rook is what you run after starting your terminal, in place of
tmux.
The bet. The multiplexer and the jump list are solved — tmux, zoxide.
What is not solved is the layer above them: N agents in N sessions, each
producing turns, and no way to route attention across them. That layer is
the product. Everything else is a dependency and stays one — until its
data model caps the product, which is how
sesh's ideas got absorbed into
rook ls / preview / connect instead of staying a dependency.
What this is not. Not a terminal emulator, not an editor, not a
multiplexer. Ghostty and neovim are tenants. tmux is a depends_on, never
vendored.
What is here. rook boots a bare tmux: its own server socket (-L rook) under a config rook generates — the user's ~/.tmux.conf is
never read, their tmux is never touched. internal/tmux.Settings is the
proxy: one field per tmux option, rendered atomically to
~/.local/state/rook/tmux.conf at boot, reconciled live via
set-option on the socket. Colours are ANSI names on purpose: the glass
owns the palette, rook owns structure and emphasis.
Run it.
make install # go build -o rook ./cmd/rook, then into ~/.local/bin
rook # attaches to a session named for the current directory
One binary, over a rook-owned tmux server. rook ls / preview / connect
are the session manager; the bottom strip carries per-pane git and the
active pane's spend; the attention feed routes what needs you across
every session (vera is its first publisher).
Agents. prefix a (or rook agents) is a sidebar: spaces (live
sessions, with their branch) and agents (who is working where — waiting
● needs you, working ●, done), a dot and two lines each. Enter goes
there; Esc closes. prefix A turns it into a sidebar: a panel on the
left that follows you to every window and session (tmux hooks hand it
over) until prefix A parks it. rook agents --json is the agent list
for machines.
The companion. One resident is named in the config and rook knows her by sight — vera by default — so "is she already open, and where" is a question rook answers rather than a thing you go and look for:
rook companion # vera · main, window 1 · pane 7 · in front of you · open 20m
rook companion --json # the same, as rook publishes it; exit 1 when she is not open
It is what the engine can see in its own panes and nothing more — the
companion block of rook state, which is where anything that wants
to watch it should read it. Open on your phone is not open in rook.
[companion]
command = "vera" # or program = "vera"; program = "" turns the slot off
The chrome is tmux. Tabs are the status line (window names, the active one raised, agent state as ● / ✳); every pane wears its name on its top border — claude, zsh, agents — with its git place beside it; the sidebar is a pane. Nothing is drawn by rook itself, so every terminal feature passes straight through.
Worktrees. One agent, one branch, one checkout, one session — and a
lifecycle that ends with all of them gone. rook wt is the manager — a
TUI that draws the repo's worktrees with branch, dirty, ±distance from
main, ● live session and the agent's state in it, refreshed live.
prefix w runs the same program in a popup. Enter opens, n cuts a
new one, m merges it home, d removes (D to force). The same verbs
are plain commands from any checkout of the repo:
rook wt ls # the rows, once; --json for machines
rook wt new agent-a # ../<repo>--agent-a on branch agent-a, session opened, switched to
rook wt merge agent-a # merge into main, then remove worktree + session + branch
rook wt rm agent-a # refuses dirty or unmerged; --force to discard
Files git doesn't carry but a checkout needs are conventions in
rook.toml, copied or linked from the main checkout into every new
worktree:
[worktree]
copy = [".env"]
link = ["node_modules"]
Pulling things back. The previous rook — the Zig app, the plugin
vocabulary, the environments graph, the providers — is intact on the
pre-tmux branch. Take a file when it earns its place, not by default:
git checkout pre-tmux -- docs/plugins/VOCABULARY.md
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
rook
command
Command rook is the front door to the rook multiplexer.
|
Command rook is the front door to the rook multiplexer. |
|
rookd
command
rookd keeps rook alive: it supervises the mux server (adopting one that already runs — rookd is a nanny, not an owner: the server is spawned into its own session and survives rookd restarts) and runs the web bridge in-process.
|
rookd keeps rook alive: it supervises the mux server (adopting one that already runs — rookd is a nanny, not an owner: the server is spawned into its own session and survives rookd restarts) and runs the web bridge in-process. |
|
internal
|
|
|
agents
Package agents is the attention layer's face: a sidebar.
|
Package agents is the attention layer's face: a sidebar. |
|
attention
Package attention is rook's inbound contract: anything that wants a say in rook's chrome — the status bar, the picker, the preview — writes items into the attention feed, and rook renders them without knowing who wrote them.
|
Package attention is rook's inbound contract: anything that wants a say in rook's chrome — the status bar, the picker, the preview — writes items into the attention feed, and rook renders them without knowing who wrote them. |
|
config
Package config loads rook's user configuration from ~/.config/rook/rook.toml (XDG_CONFIG_HOME respected).
|
Package config loads rook's user configuration from ~/.config/rook/rook.toml (XDG_CONFIG_HOME respected). |
|
mux
Package mux is the Go layer's client for the Zig engine.
|
Package mux is the Go layer's client for the Zig engine. |
|
picker
Package picker is the workspace picker prefix-s floats in a popup: fzf over the workspaces, where enter switches to the row under the cursor and ctrl-o creates the one you typed.
|
Package picker is the workspace picker prefix-s floats in a popup: fzf over the workspaces, where enter switches to the row under the cursor and ctrl-o creates the one you typed. |
|
sessions
Package sessions is rook's own session model — the layer that used to be delegated to sesh.
|
Package sessions is rook's own session model — the layer that used to be delegated to sesh. |
|
tmux
Package tmux boots and addresses the rook-owned tmux server.
|
Package tmux boots and addresses the rook-owned tmux server. |
|
tui
Package tui is what rook's Bubble Tea faces share: the palette.
|
Package tui is what rook's Bubble Tea faces share: the palette. |
|
webd
Package webd bridges browsers to the engine socket and serves the web client.
|
Package webd bridges browsers to the engine socket and serves the web client. |
|
worktree
Package worktree is rook's worktree-per-agent model: one git worktree, one branch, one rook session, and a lifecycle that ends with the branch merged and all three gone.
|
Package worktree is rook's worktree-per-agent model: one git worktree, one branch, one rook session, and a lifecycle that ends with the branch merged and all three gone. |
|
worktree/ui
Package ui is the worktree manager's face: a Bubble Tea program that draws the repo's worktrees with live state and runs the lifecycle verbs on them.
|
Package ui is the worktree manager's face: a Bubble Tea program that draws the repo's worktrees with live state and runs the lifecycle verbs on them. |
|
sdk
|
|
|
provider
module
|