worktree

Git Worktree Workflow

Run parallel agent sessions on independent tasks using git worktrees.

When to Use

• You have 2+ independent tasks that touch different files
• Tasks are on separate tracker issues
• You want to multiply throughput by running parallel sessions

When NOT to Use

• Tasks touch the same files (merge conflicts)
• One task depends on the output of another
• Quick single-file fixes (just do them sequentially)

Step 0: Claim the Branch

Worktrees stop two sessions sharing a checkout. They do nothing about two sessions sharing a branch, which is the collision you actually hit once more than one agent runs at a time - they all authenticate as the same git identity, so nothing tells them apart.

Checking is not claiming. The check only reads the remote: two sessions can both run it, both get exit 0, and both start. Acquire a lease as well.

# 1. is anyone already here? (from the repo root; this only reads the remote)
bin/claim-branch.sh feature/<task-name>

# 2. if that said free, create the worktree (see "Setup a Worktree" below)
git worktree add ../<repo>-worktree-<task-name> -b feature/<task-name>

# 3. RESERVE it, from INSIDE the new worktree - this is the step that holds the branch
cd ../<repo>-worktree-<task-name>
bin/claim-branch.sh --acquire feature/<task-name> --me <session-id> --harness claude-code

If step 3 exits 1, someone took the branch between your check and your acquire: remove the worktree you just made and pick another name. Pass the branch the way git switch takes it (feature/x, not refs/heads/feature/x or origin/feature/x; those exit 2). --me and --harness take only [A-Za-z0-9._:-], and may not contain RELEASE or CLAIM as a whole word.

Exit 0 free, 1 claimed by someone else (pick another branch or coordinate), 2 could not tell. Exit 2 never means free. And a clean fast-forward is not permission - that is exactly what a collision looks like from the inside, so "it merged fine" is not evidence that nobody else was there.