How to Run Two Claude Code Agents on the Same Repo Without Destroying Your Git History

You want Claude to build a new API endpoint while simultaneously refactoring your test suite. Two separate tasks, no real dependency between them. The obvious move: open two terminal tabs, run Claude Code in each, and let them work in parallel.

This works right up until both agents try to modify package.json, or one rebases while the other is mid-commit, or they both edit a shared utility file and produce a git history that looks like abstract art.

Running two Claude Code agents on the same branch in the same working directory is a recipe for merge conflicts, lost work, and confused agents.

Why two agents on one branch breaks

Git is designed for one writer at a time in a given working directory. When two Claude Code sessions run in the same repo on the same branch, they share:

  • The working tree. Both agents see and modify the same files. If agent A edits utils.ts and agent B edits utils.ts a minute later, one set of changes gets overwritten.
  • The staging area. git add is global to the repo. If agent A stages files while agent B is still editing, the commit will include a mix of complete and incomplete changes.
  • The branch pointer. Both agents commit to the same branch. This creates a tangled commit history where changes from different tasks are interleaved.

Even if the agents are working on “different files,” shared configuration files, lock files, and auto-generated code create unexpected collisions. Claude often touches more files than you’d expect — updating imports, adjusting configs, running formatters.

The git worktree solution

Git has a built-in feature for exactly this problem: worktrees. A git worktree creates a second working directory for the same repository, with its own branch, staging area, and file state — while sharing the same .git history.

Setting it up manually:

# From your main repo directory
git worktree add ../my-repo-worktree-1 -b feature/api-endpoint
git worktree add ../my-repo-worktree-2 -b feature/test-refactor

Now you have three directories:

  • my-repo/ — your original working directory (main branch)
  • my-repo-worktree-1/ — isolated directory on feature/api-endpoint
  • my-repo-worktree-2/ — isolated directory on feature/test-refactor

Run Claude Code in each worktree directory. Both agents can commit freely without interfering with each other. When they’re done, you merge the branches like any normal feature branch workflow.

The manual worktree workflow

If you’re doing this by hand, the full process looks like:

  1. Create a worktree with a new branch for each task.
  2. Open a terminal tab pointed at each worktree directory.
  3. Run Claude Code in each tab with the appropriate task.
  4. Review each branch independently when the work is done.
  5. Merge the branches back into your main branch.
  6. Clean up worktrees with git worktree remove.

It works. But it’s a lot of ceremony for something that should be “run two agents at once.” You’re managing directories, remembering branch names, cleaning up worktrees, and keeping track of which terminal tab points to which directory.

How Crystl automates this with isolated shards

This is one of the problems Crystl was designed to solve. When you create an isolated shard in Crystl, it automatically sets up a git worktree with a dedicated branch. You don’t manage directories or branch names — you just open a new shard and start working.

The workflow:

  1. Open your gem (project) in Crystl.
  2. Create a new isolated shard. Crystl creates the worktree and branch automatically.
  3. Create a second isolated shard for the other task.
  4. Run both agents. Each has its own working directory, staging area, and branch.
  5. Review each shard’s work using the conversation history and git diff.
  6. Merge when ready. Clean up happens automatically when you close the shard.

The Crystal Rail shows all your active shards, so switching between agents is one click. Notifications tell you when a shard finishes or needs approval, so you don’t have to keep checking.

When you actually need parallel agents

Not every task benefits from parallelism. Here’s when it makes sense:

  • Independent features. Building a new page while adding a background job. No shared files, clean separation.
  • Test and implementation. One agent writes tests, another implements the feature. Merge the test branch first, then have the implementation agent ensure tests pass.
  • Refactoring alongside feature work. One agent refactors module structure while another adds new functionality. Merge the refactor first, rebase the feature branch.
  • Exploration. Have two agents try different approaches to the same problem. Pick the better one, discard the other.

The key insight is that parallel agents work best when their tasks have minimal file overlap. Even with worktrees, you’ll still need to resolve merge conflicts if both agents modify the same code. The difference is that with worktrees, those conflicts are clean git merges rather than corrupted working directories.

Summary

Running multiple Claude Code agents in parallel is one of the most productive patterns in agentic coding. But doing it naively — two terminals, same branch, same directory — creates more problems than it solves.

Git worktrees are the right foundation. Whether you manage them manually or let Crystl handle it through isolated shards, the principle is the same: give each agent its own workspace, let them work independently, and merge the results.

Crystl is free — sign up at crystl.dev/login.