A space per branch

A space per branch

The picker

The worktree picker lists every worktree of the repo you are in, labeled by branch, with the primary and any locked ones marked. From it you can create one — new branch, new directory — open one in a space of its own, or remove one you are finished with.

When git refuses something, the picker shows you git’s own words along its footer rather than a generic failure, so a locked worktree or a dirty branch reads the way it would in a shell.

What a worktree space looks like

A space opened for a worktree titles itself from the branch and wears a marker glyph, so you can tell it apart from the space holding your main checkout. Beside the title it carries the branch’s CI verdict from the last status fetch — the first thing you want to know about a branch an agent has been pushing to.

From there it is an ordinary space: split it, put an agent pane in it, leave a shell running. Closing the space does not touch the worktree on disk.

Environments that come up with the branch

Most branches need more than an editor: a dev server, a watcher, a database. A project can declare up and down scripts, and bringing the environment up runs each one in its own pane of that worktree’s space — dev server here, watcher there — so you can see all of them at once. Taking it down runs the down scripts out of sight and closes those panes.

• Each up script gets a named pane, so the space reads as a dashboard for the branch rather than a pile of shells.
• Scripts are declared once per project and reused for every worktree of it — the point is that opening the fourth branch costs nothing you had to think about.
• The worktree stays on disk when the environment goes down. Only the panes close.

# .raven-term.toml at the repo root — checked in, shared with the team
[[up]]
name = "web"
command = "npm run dev"
cwd = "marketing-site"

[[up]]
name = "agent"
command = "cargo run"

[[down]]
name = "stop"
command = "docker compose down"

That file lives with the repository, so a teammate opening the same branch gets the same environment. Your own machine can override it section by section in Settings → Projects, for the paths and services that are yours alone.

Projects

A project is a working directory you have saved — a repository, or the parent directory you keep worktrees under. Saved projects are what the picker offers you when you open a new space, and what per-project settings like the ones above attach to, so the directory you work in every day is one keystroke away rather than a path you retype. ⌘K → Projects is the way in.