Claims and worktrees — parallel agents without merge roulette

A claim is an advisory lock on a scope (path glob, directory, plan id) that tells other agents “I’m working here, stay clear”. When the claim is created, brainclaw automatically creates an isolated Git worktree under ~/.brainclaw/worktrees/<project-hash>/<branch>/ so the agent’s edits never collide with another agent’s working tree.

The flow

# Agent A claims auth scope
bclaw_work intent=execute scope="src/auth/"
# → claim clm_a created, worktree at ~/.brainclaw/worktrees/<hash>/feat_src-auth/

# Agent B tries to claim overlapping scope
bclaw_work intent=execute scope="src/auth/middleware.ts"
# → conflict: agent B sees agent A's claim before any edit happens

When the work is done:

# Agent A releases with plan status update
bclaw_release_claim id=clm_a planStatus=done
# → handoff written, worktree cleaned up, plan transitioned

Why worktrees, not branches

A branch lets two agents edit the same working directory in sequence. A worktree gives each agent its own working directory — they can work in parallel, even on overlapping branches, without stepping on each other’s npm install or node_modules.

brainclaw worktree clean prunes merged branches. brainclaw worktree merge <branch> handles the merge with auto-restoration of the main worktree state.

Claim conflicts — what to do

When two agents claim overlapping scope, the second call returns a scope_already_claimed warning with the existing claim’s id and agent. You have three options, in order of preference:

# 1. Reroute — release the existing claim and reassign to the new agent.
#    Use this when the original agent has stalled or you want a fresh take.
bclaw_coordinate intent=reroute scope="src/auth/" targetAgents=[codex] task="..."

# 2. Wait — the original agent is mid-flight. Read its handoff or assignment status:
bclaw_find entity=assignment filter={agent: "claude-code", status: "offered"}
bclaw_find entity=agent_run filter={status: "running"}
# Pick the work back up after `bclaw_release_claim` fires.

# 3. Force-release — the agent abandoned without releasing. Last resort, audit the action.
brainclaw release-claim <claim_id> --force --reason "abandoned session"

bclaw_coordinate intent=reroute is the cleanest path because it transitions the assignment lifecycle correctly. Force-release leaves a gap in the audit chain — only use it when the original agent is truly gone.

”My worktree got wiped after a merge”

Resolved as of v1.5.0 (pln#498) — detachWorktreeJunctions runs before git worktree remove on Windows so git’s recursive rm can’t follow the node_modules junction back into the main repo. If you see this on v1.4.x or older, upgrade.

What goes wrong without claims

Without claims, two agents pick up the same task in parallel, both edit the same files, both run their tests in the same node_modules, and the second one to commit discovers the conflict at merge time. One side gets discarded — wasted compute and tokens.

See parallel feature work for the full pattern in context, or the troubleshooting guide for recovery from stale claims.