How do I stop Claude Code agents from overwriting each other's files?

Give each agent its own git worktree and branch, so no two agents ever share a checkout: claude --worktree <name> does it in one command. Then split the work so each agent owns a different set of files, and merge the branches one at a time, running your tests on the merged result. Worktrees stop agents from overwriting each other's files. They don't stop two correct changes from breaking each other once merged.

Why it happens

Two Claude Code sessions started with plain claude in the same folder edit the same working tree. Neither knows the other exists. One rewrites a file the other just changed, or runs a formatter over half-finished work. Git can't help because nothing has been committed yet.

Without Kanbell: isolate, split, merge in order

1. One worktree per agent

claude -w auth-refactor
claude -w billing-fix

Each session works in .claude/worktrees/<name>/ on its own branch (worktree-auth-refactor, worktree-billing-fix). A worktree is a separate directory with its own files and branch, sharing the repository's history.

While a session is isolated in a worktree, Claude Code blocks:

• Edit, Write and NotebookEdit calls that target the main checkout;
• shell commands whose working directory is the main checkout;
• git commands redirected into the main checkout (git -C, --git-dir, GIT_DIR, GIT_WORK_TREE, or a cd first).

The same checks apply to subagents that session spawns.

If you prefer plain git:

git worktree add ../myapp-auth -b auth-refactor
git worktree add ../myapp-billing -b billing-fix

Git refuses to check out a branch that another worktree already has checked out, unless you pass --force. That alone prevents two agents from committing to the same branch.

2. Use the modes that isolate on their own

• Background sessions started from claude agents or with claude --bg move into a worktree under .claude/worktrees/ before they edit files in a git repository.
• Subagents can each get a temporary worktree: add isolation: worktree to the subagent's frontmatter, or ask Claude to "use worktrees for your agents".
• Agent teams don't use worktrees. The docs are direct about it: two teammates editing the same file leads to overwrites, so give each teammate a different set of files.

3. Split tasks along file boundaries

Worktrees move the collision from "while editing" to "while merging". To avoid it there too, give each agent a scope that doesn't overlap:

• one agent per module or package;
• shared files (routes, schema, config, lock files) owned by one agent only;
• state the boundary in the prompt: "only edit files under src/billing/".

When one session changes something another depends on, cross-session messaging lets Claude warn the other session. It is on with nothing to enable on Claude Code v2.1.224 or later on macOS and Linux, and v2.1.234 or later on native Windows.

4. Merge one branch at a time

git switch main
git merge --no-ff worktree-billing-fix
npm test            # or your test command
git merge --no-ff worktree-auth-refactor
npm test

Run the tests after each merge, not only on each branch. Two branches can each pass their tests and still break once combined, for example when one renames a function the other starts calling.

5. Clean up

git worktree list
git worktree remove ../myapp-billing

When you exit, Claude Code removes a clean --worktree worktree if the session has no name, asks first for a named session (-n), and asks before removing one that holds work.

Limits of this method

• Shared state outside the checkout. A worktree isolates files in the working tree. A local database, a dev server port or a Docker volume is still shared between agents.
• Shell commands can escape. Claude Code's checks read edit paths, command directories and command text. A cp or a shell redirect into the main checkout isn't refused by them; your permission and sandbox settings still apply.
• Merge conflicts move, they don't vanish. Overlapping scopes still conflict at merge time.
• You lose sight of who touched what. With five worktrees, knowing which branch changed which file means running git diff in each.

With Kanbell

Kanbell doesn't prevent conflicts. It makes the parallel work easier to watch while you apply the method above.

• Git panel beside the terminals. Changes, diffs, history and worktrees for the project sit next to the sessions, so you can see what each worktree changed before you merge.
• One window per project, with real terminals in panes and tabs: one per worktree, side by side.
• State per agent. For Claude Code: working, waiting or done, and whether it waits on a question or a permission. An orange dot and ⌘⇧J take you to the agent that needs you.
• A board (local or GitHub Issues) to write down which agent owns which scope, and to launch an agent from a card with the brief pasted for you to review before you press Enter.

Kanbell runs on macOS (Apple Silicon), with no account and no Kanbell server.