Why Your Claude Code Agents Keep Overwriting Each Other's Files

You set up two Claude Code sessions on the same project. One is refactoring the API layer. The other is updating the test suite. Ten minutes later, one agent overwrites a file the other just edited. The refactor is half-applied, the tests reference code that no longer exists, and you’re doing a git checkout -- . to start over.

This isn’t a Claude bug. It’s a filesystem problem — and it has a clean fix.

The root cause: one directory, two writers

When you open two terminal tabs and run claude in both, both sessions operate on the exact same working directory. Every file read, every file write, every git diff — they all hit the same files on disk.

Agent A edits src/api/routes.ts. Agent B reads src/api/routes.ts two seconds later and sees Agent A’s half-finished changes. Agent B now has incorrect context. It makes its edits based on code that’s mid-refactor, producing something that doesn’t compile.

Or worse: both agents edit the same file at the same time. The last write wins. The first agent’s changes vanish silently.

This is a classic concurrency problem. Two processes writing to shared mutable state without coordination. The terminal doesn’t know about it. Git doesn’t prevent it. Claude doesn’t detect it. Nothing stops it from happening.

Why git stash doesn’t fix this

The instinctive fix is to stash one agent’s work, let the other finish, then pop. But this falls apart immediately in practice.

You can’t stash while an agent is running. Claude is actively editing files. If you stash mid-edit, you pull the rug out from under it. Claude will continue making edits that reference code that’s no longer there.

Stash conflicts are silent and confusing. When you git stash pop and there’s a conflict, the error messages are vague. You can’t easily tell which parts of the conflict came from which agent’s work.

Stashing serializes your work. The whole point of two agents was to run them in parallel. If you’re constantly stashing and switching, you’ve added overhead without gaining speed.

Why “just use branches” also doesn’t work

“Just check out a different branch in each terminal tab.” This sounds right but doesn’t work. Two terminal sessions in the same directory share the same working tree. git checkout in one tab changes the files for both.

You could clone the repo a second time, but then you’re maintaining two separate git histories, two sets of remotes, double the disk space, and you still need to sync changes between them manually.

The real fix: git worktrees

Git worktrees solve this at the filesystem level. A worktree is a second working copy of your repo that shares the same .git directory — same history, same remotes, same objects — but checks out its own branch into its own directory.

git worktree add ../my-project-refactor -b refactor/api

Now you have two directories:

  • my-project/ — your main working copy, on main
  • my-project-refactor/ — a separate working copy, on refactor/api

Run Claude in each directory. They can’t overwrite each other because they’re editing different files in different locations. When both agents are done, merge the branches with standard git operations.

This is the correct solution. Two agents, two directories, two branches, zero conflicts.

The manual setup gets old fast

Worktrees work perfectly, but the workflow has friction:

  • You create the worktree directory with git worktree add
  • You cd into it and run claude
  • You keep track of which terminal tab is in which directory
  • When you’re done, you merge the branch, delete the directory, and run git worktree prune
  • If you forget to clean up, you get stale worktree references that cause confusing errors later

For a one-off task, this is fine. For daily parallel work, it becomes a tax on every session.

How Crystl removes the friction

Crystl automates the entire worktree lifecycle. When you create an isolated shard, Crystl creates a git worktree behind the scenes, names the branch, opens the session, and manages the directory. You never touch git worktree directly.

Each isolated shard is visually distinct in the Crystal Rail — marked with a branch icon and labeled with its branch name. You can see at a glance which shards are isolated and which are sharing the main working directory.

When the work is done:

  1. Open the Isolation panel in the shard bar
  2. Choose Merge to main
  3. Crystl rebases, merges, cleans up the worktree, and closes the shard

Or just close the shard — Crystl prompts you to Merge to Main, Keep Branch, or Discard.

If something goes wrong — a crash, a restart — orphaned branches appear in the Isolation panel for one-click reattachment. Intact worktrees are reused as-is, preserving any uncommitted changes.

Preventing the problem entirely

The file-overwriting issue is entirely preventable. The rule is simple: never run two Claude Code agents in the same working directory if both might edit files.

For read-only work — asking questions, reviewing code, exploring the codebase — a shared directory is fine. But the moment you have two agents making changes, you need isolation.

Whether you set up worktrees manually or let Crystl handle it, the fix is the same: give each agent its own copy of the repo. The conflicts disappear because the agents can no longer see each other’s changes.

Get Crystl for free to get isolated worktree sessions without the manual setup.