This is the end-to-end shape the rest of the docs assume: one large repo, several agents working on it at once — each in its own worktree, on its own branch — and one person reviewing and merging what comes back.
The shape of it#
Five lines, before any commands:
- A branch is a task — one unit of work, usually one agent session.
- Each task gets its own worktree.
oak worktree addmakes a second checkout from one you already have, on a new branch off the latestmain, without downloading anything that checkout holds. - Commits are checkpoints; the branch description is the message.
- Publishing isn't merging. Each agent pushes its branch and stops. Nothing reaches
mainuntil a person merges it. - Merging squashes.
maingets one commit per task, however many checkpoints the agent made.
If you're coming from Git: oak worktree add is git worktree add; the branch description does what a PR title and body do, minus the PR; and the squash merge is what "Squash and merge" does, except it's the only merge there is.
1. Set up#
curl -fsSL https://oak.space/install | sh
oak login
oak repo list --org acme # which repos can you clone?
# acme/monorepo
# acme/infra
# acme/docs
mkdir acme && cd acme # any directory works
2. Fan out#
One task = one directory = one worktree = one branch. Tasks are isolated by construction: separate directories, separate working trees, separate branches, and none of them can touch main. A branch can be checked out in only one worktree at a time.
Clone once, then start each task in a worktree beside it:
oak clone acme/monorepo --shallow
cd monorepo
oak start "fix auth redirect" --worktree # ../monorepo-fix-auth-redirect
oak start "add search index" --worktree # ../monorepo-add-search-index
oak start "bump tokio" --worktree # ../monorepo-bump-tokio
Each oak start --worktree makes the checkout, creates the branch from main's head, sets its description and pushes it. On APFS, btrfs and XFS the new checkout's store is a copy-on-write copy of the first one's, so it takes almost no extra disk. If the tasks only need part of the monorepo, make the first clone a sparse clone with --path; its worktrees hold the same directories.
Now launch one agent per worktree. With Claude Code:
claude -p "Work in ../monorepo-fix-auth-redirect, on the branch already started there.
The OAuth callback drops the ?next= param. Fix it, then finalize with oak finish." &
claude -p "Work in ../monorepo-add-search-index, on the branch already started there.
Add a trigram index behind the search-index flag. Finalize with oak finish." &
claude -p "Work in ../monorepo-bump-tokio, on the branch already started there.
Bump tokio to 1.42 across the workspace and fix the fallout. Finalize with oak finish." &
wait
An agent can make its own worktree too: oak start "<summary>" --worktree --json returns the folder in worktree. A cross-repo task gets one worktree per repo, started with the same summary in each.
3. Each agent finishes its own branch#
Each agent ends with:
cd ./fix-auth-redirect
oak finish --desc-file /tmp/desc.md --json
One command that checks it can publish, sets the branch description from the file, checkpoints anything uncommitted, and pushes. If a step fails, nothing is lost and the JSON names the next command.
Pushed branches appear live on the repo's Branches page, and oak branch triage --remote lists them from anywhere.
4. Review what came back#
Three branches, and you don't want to switch your working tree three times. Start with triage:
oak branch triage --remote # every open branch, scored
oak branch triage --remote --only mergeable
oak branch triage --remote --only ambiguous
Then read the ones that need you:
oak diff fix-auth-redirect # full-screen, no checkout
oak branch diff add-search-index --diff-mode net-merge
Or do it in the browser: the Branches page lists every open branch, and each one opens to its diff with a Merge button. Reviewing branches has the details.
5. Land them#
Merging is a decision, so it happens from somewhere you control — the web UI or your own checkout:
# In a clone of the repo (a shallow or sparse one is fine)
oak switch fix-auth-redirect
oak merge # squash onto main
Or check off the clean branches on the Branches page and click Merge selected.
When a branch conflicts, don't re-run the agent from scratch — go back to the task's worktree, still on that branch, and fix it in place:
cd ../monorepo-fix-auth-redirect
oak pull # merge the new main in; conflicts surface here
# resolve, or hand this worktree to an agent
oak pull --continue
oak commit && oak push
If the worktree is gone, make a new one with oak worktree add ../fix-auth-redirect --branch fix-auth-redirect. That's also how a follow-up prompt keeps working on a branch an agent already pushed.
6. Clean up#
Once a task's branch is merged or closed, remove its worktree. oak worktree remove refuses while the worktree has uncommitted changes or commits the server doesn't have:
oak worktree list
oak worktree remove ../monorepo-bump-tokio
All of it at once#
# once per machine
curl -fsSL https://oak.space/install | sh && oak login
# fan out
oak clone acme/monorepo --shallow && cd monorepo
oak start "fix auth redirect" --worktree
oak start "add search index" --worktree
claude -p "Work in ../monorepo-fix-auth-redirect …" &
claude -p "Work in ../monorepo-add-search-index …" &
wait
# review, checkout-free
oak branch triage --remote --json
oak diff <branch>
# land
oak switch <branch> && oak merge # or Merge in the web UI
# remove worktrees whose branches have landed
oak worktree remove ../monorepo-fix-auth-redirect
oak worktree remove ../monorepo-add-search-index
Scaling up is more of the same: more worktrees, more agents. The limit worth knowing is your own review throughput, which is what oak branch triage exists to protect.