Parallel features

Build several features at once in one repository: one worktree and one editing agent per feature, plus a reviewer agent that checks each diff when the builders finish.

Set up the worktrees

Cut one worktree per feature, named after it:

beswarm worktree add --name feat-auth --workspace api
beswarm worktree add --name fix-rate-limit --workspace api

Each add cuts a branch with the same name, checks it out in .worktrees/<name>, and opens a terminal there. It prints that terminal's id:

created worktree feat-auth at ~/code/api/.worktrees/feat-auth with terminal 18da9fb9f3d38fc0-3

Pass that id to agent start so the agent runs inside the worktree.

Start one builder per worktree

Start each builder in its worktree's terminal, in a shared group, with success criteria in the prompt. Tell builders to commit: the reviewer reads the branches, and git refuses to remove a worktree with uncommitted changes.

beswarm agent start --name auth --agent claude <terminal-id> --group features \
  --prompt "Add OAuth login. Run the test suite and lint, then commit your work."
beswarm agent start --name ratelimit --agent codex <terminal-id> --group features \
  --prompt "Fix the rate limiter off-by-one. Add a regression test, run it, then commit."

Wait for the builders

beswarm agent wait auth --until done,blocked --timeout 3600
beswarm agent wait ratelimit --until done,blocked --timeout 3600

If one comes back blocked, read its screen with agent read --source visible and decide how to answer. See Safety rules.

Review each diff

Keep the reviewer separate from the builders, in a worktree of its own. Every worktree shares the repository's branches, so it can diff each feature branch:

beswarm worktree add --name review --workspace api
beswarm agent start --name reviewer --agent claude <terminal-id> --group features \
  --prompt "Review git diff main...feat-auth and git diff main...fix-rate-limit. Don't edit files. Report only actionable findings to ../../reports/review.md." \
  --wait --timeout 1200

../../reports/ is the reports/ folder of the main checkout, so the report shows up in the Artifacts panel and in beswarm artifact list.

Clean up

Once you've merged what you want to keep, close the group and remove the worktrees:

beswarm agent close --group features
beswarm worktree remove --name feat-auth --workspace api
beswarm worktree remove --name fix-rate-limit --workspace api
beswarm worktree remove --name review --workspace api