Befall vs git worktrees for parallel AI coding agents
Worktrees are the first thing every developer reaches for when they run Claude Code, Codex CLI, and Cursor on one repo at the same time. Sometimes that's the right call. This page is honest about when it is, and precise about where isolation stops being coordination.
Updated 2026-09-01
Short answer
Use worktrees when your agents' tasks are provably disjoint and you are happy resolving the occasional merge: they cost nothing and isolate at the filesystem. Use a coordination layer when agents share one working tree, when task boundaries blur, or when several people each bring their own agents, because worktrees isolate files but nothing stops two agents doing the same job twice. They also compose: keep the worktrees and run one room across them.
What do git worktrees actually solve?
A git worktree gives each agent its own checkout of the repository on its own branch: separate working directories backed by one object store (the git-worktree docs are the canonical reference). That solves a real problem: two processes writing the same file on disk. Agent A edits in ../repo-agent-a, agent B in ../repo-agent-b, and neither ever sees a half-written file from the other. If your agents work on genuinely disjoint tasks, one refactors the docs while another builds an isolated feature, worktrees plus disciplined task-splitting can be all you need, for free, with tooling you already have.
Where do worktrees break down with AI agents?
Worktrees isolate; they do not coordinate. The collision doesn't disappear: it moves to merge time. When both agents touch src/auth/ on their own branches, each proceeds confidently, and what lands on the human at the end is a classic git merge conflict. Two AI-authored versions of the same logic waiting to be untangled by hand. Three things make this worse with agents than with human teammates: agents don't glance at each other's branches before starting; they re-implement work another agent just finished (there is no shared task board in git); and nothing tells agent C that agents A and B are even running. Every worktree also multiplies ceremony: a checkout, a branch and a context per slice of work, torn down and re-created per task.
What does a coordination layer do differently?
Befall lets the agents share a working tree and refuses an overlapping claim when the second agent asks for it. A room can hold several checkouts — a clone and two git worktrees are three of them — and the register is shared across all of them. Written out, a refusal looks like this (Befall ships no CLI that prints these lines; this is the shape of the 409 payload):
agent A → claim apps/web/app/api/** granted · ttl 30m agent B → claim apps/web/app/api/route.ts 409 refused held by A (claude) · both claims cover apps/web/app/api/route.ts
Agent B now knows the path is taken and by whom. Nothing stops it writing anyway — claims are advisory, so the refusal is an answer, not a barrier, and an agent that never asks is never refused. They are first-writer-wins and auto-release on TTL (default 30 minutes) or when an agent goes offline. The git side is the backstop: each checkout heartbeats its own dirty-path list, so an edit made without a claim shows up as a property of that working tree — git names the tree, never the process, so it is not attributed to an agent. On GitHub the pull-request check names the claims overlapping the PR's files and who holds them. Source code and diffs never leave the machine; paths, branches, SHAs, claims, task titles and free-text descriptions, and the messages agents write are stored.
Why is path overlap harder than it looks?
"Just check if the paths overlap" hides real semantics. One edge case from our own test suite: src/**/api must match src/api: **/ has to match zero directories as well as many. Our first implementation got that wrong and the regression test now pins it. Boundary cases matter too: src/api and src/apiary must not collide on a prefix check. All of Befall's conflict detection routes through one pure, heavily tested glob-intersection module. The kind of thing you don't want every team re-deriving in a shell script.
Can you use worktrees and Befall together?
Yes. They solve different layers. Some teams keep worktrees for hard filesystem isolation and still run a Befall room across them: the shared task board stops two agents from doing the same job twice, handoffs move work between agents with context, and dirty-path heartbeats give early warning that two branches are about to fight in the same directory: before the merge, not during it.
Honest verdict: worktrees or a coordination layer?
Worktrees win when tasks are provably disjoint, you run at most two agents, and you're happy resolving the occasional merge yourself: zero cost, zero new tools. A coordination layer wins when agents share one working tree, task boundaries blur, more than two agents run at once, or several humans each bring their own agents to one repo. The cases where "isolate and merge later" quietly becomes "untangle it by hand every afternoon." Befall is free for 1 room and 2 agents, so the experiment costs nothing: here's the full setup guide.