rota

Your first round

Finish getting started first: install rota, install the skills and run rota setup in the project. This page walks you to a first parallel round in herdr or tmux: an orchestrator in one pane, workers in tabs (tmux: windows), each on its own issue. Parallel rounds has the details behind each step.

1. 📋 Prerequisites

  • A git repo with an origin, and the base branch (usually main) pushed.
  • gh (GitHub) or glab (GitLab), logged in.
  • A few open issues with acceptance criteria. A round only offers issues that have them (or a design or plan note).
  • claude (Claude Code) on your PATH.
  • A terminal host: herdr 0.9.x, from herdr.dev, or tmux. herdr reports each worker’s state directly; under tmux rota reads the panes instead.

2. ⚙ Slots and the merge check

rota setup already wrote .rota/; commit .rota/, .claude/agents/, AGENTS.md, CLAUDE.md and .gitignore. The .claude/agents/rota-*.md files are subagent definitions that workers use to pick a cheaper or stronger model per job. Setup sets three worker slots. For a small first round, use two:

rota config set round.slots 2

Then tell the gate how to check a merge. test.full is the command that runs your whole test suite. The gate runs it on a scratch merge of the PR before the PR lands:

rota config set test.full "go test ./..."   # your project's own test command

While test.full is empty the gate refuses to merge, because nothing would check the result. --no-verify merges anyway, on purpose. Don’t use it for a first round.

3. Extra accounts (optional)

Skip this if you have one Claude account.

For each additional account, create a config dir and log in once. rota skills install copies the skills into every account you list in step 4, so re-running it there covers them (it skips a dir that does not exist).

mkdir ~/.claude-b
CLAUDE_CONFIG_DIR=~/.claude-b claude          # log in, then exit

4. Tell rota about the accounts

Account paths are machine-specific, so they go in .rota/config.local.json (gitignored), not the tracked config. Edit it by hand, list your main account too, and use absolute paths:

{
  "round": {
    "accounts": [
      { "kind": "claude", "name": "main", "dir": "/home/you/.claude" },
      { "kind": "claude", "name": "b", "dir": "/home/you/.claude-b" }
    ]
  }
}

Then check them, and install the skills into each one:

rota worker account list
rota skills install

5. Start herdr or tmux

herdr                       # or: herdr --session <name>
tmux new -s <name>          # with tmux instead

Open a pane and cd to the project root. Run everything from here on in that pane, so the round can detect its host.

6. Install the herdr integration (herdr only)

Skip this under tmux. herdr reports each worker’s state (working, blocked, idle) only for agents it has an integration for. Install it once per account:

herdr integration install claude
CLAUDE_CONFIG_DIR=~/.claude-b herdr integration install claude   # each extra account
herdr integration status

7. Orchestrator permissions

The orchestrator runs many rota, git and forge commands. Allow them in .claude/settings.local.json so it doesn’t stop at every prompt:

{
  "permissions": {
    "allow": [
      "Bash(rota *)",
      "Bash(git *)",
      "Bash(gh *)",
      "Bash(glab *)"
    ]
  }
}

gh covers GitHub and glab GitLab; a rule for a CLI you don’t use never matches. Bash(rota *) allows rota with any arguments; the older Bash(rota:*) form means the same. See Claude Code’s permission rules. Running with --dangerously-skip-permissions is your call; rota doesn’t do it for you. Workers launch with permissions skipped by default (round.commands.claude), because nobody is in their pane to answer a prompt. See configuration.

8. Unattended hooks (skip for now)

rota hook install adds handoff hooks so a long round survives the orchestrator’s context filling up. It writes .claude/settings.local.json by default; --scope project and --scope user also exist, --wrap-statusline keeps a statusline you already have, and rota must be on PATH.

For a first round, skip the hooks and keepalive both. Hooks without keepalive mean the orchestrator exits at the context threshold and nothing restarts it. Install them together later: unattended rounds.

9. 🩺 Run doctor

rota doctor

Fix every fail; each one prints the command or edit that fixes it. Run it inside the herdr or tmux pane so it sees the host. See doctor and reap.

10. 🚀 Launch the orchestrator

In the pane, at the project root:

rota orchestrate

It runs rota doctor, then opens an orchestrator session that has already started /rota-orchestrate. Tell the orchestrator what you want, for example “run a round on issues 12 and 13”. Bare rota then Enter does the same; the palette, the harness choice and the account it starts under are described in launching a round.

The skill runs rota doctor again, then rota round start. That takes the orchestrator lease, creates the worker slots and lists the ready issues, and it detects herdr or tmux from the pane it runs in. It starts no worker yet. The orchestrator then picks the slate and assigns each issue with rota round assign, which cuts a branch and starts a worker in a new tab.

11. 👀 Watch

Each worker shows up as a herdr tab or a tmux window. To see all slots with their host, PR and drift:

rota round status

No need to poll. The orchestrator waits on rota round wait and wakes when a slot is done, blocked or dead. A slot is free as soon as its worker opens a PR: the orchestrator gives it the next issue while that PR waits for review.

12. Merges and escalations

Workers open PRs and never merge. For each finished PR the orchestrator reads the diff, runs the gate (rota worker gate) on the merged tree and merges on a pass. The gate also refuses a PR whose body lacks Closes #N for its issue (an issue labelled partial-slice is exempt) and a PR with a recorded FAIL review verdict. By default (ship.mergeApproval is none) a passing gate merges. If you set all or paths, the gate asks you on the PR thread first and merges only after you reply approve, approved, yes, lgtm or ship it. See merge approval.

When a worker or the orchestrator needs a human decision, it posts the question on the issue or PR thread, or asks in the pane. Answer there. A line starting with m: typed into a pane counts as a maintainer answer: details.

13. 🏁 Wind down

When the slate is done, tell the orchestrator to finish. It runs rota round wind-down, which re-verifies the base branch, parks every slot and releases the lease. Then clean up what is left:

rota reap            # preview
rota reap --apply    # remove the leftovers that hold no work

See doctor and reap.

➡ Next

Edit this page on GitHub