Example: a fleet of agents

End to end: several agents on one big repo, each in its own clone on its own branch, then review and merge.

Markdown

All pages

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:

  1. A branch is a task — one unit of work, usually one agent session.
  2. Each task gets its own worktree. oak worktree add makes a second checkout from one you already have, on a new branch off the latest main, without downloading anything that checkout holds.
  3. Commits are checkpoints; the branch description is the message.
  4. Publishing isn't merging. Each agent pushes its branch and stops. Nothing reaches main until a person merges it.
  5. Merging squashes. main gets 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.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].