Parallelizing Claude Code: Git Worktrees and Agent Workflows

When you move from using one AI agent to orchestrating a fleet, the bottleneck shifts from the LLM's context window to your local file system. If you have tried running multiple instances of Claude Code in a single directory, you have seen the errors: .git/index.lock exists, or one agent overwrites the progress of another because they are both contending for the same HEAD.

In my studio, I run a fleet of agents to handle the work of a team. To keep the machine moving, I had to solve the contention problem. The solution isn't more complex branching logic; it is physical isolation through git worktrees. This is how I parallelize four or more Claude Code agents without merge conflicts or file loss.

The Git Lock Bottleneck

Standard claude-code-workflows usually involve opening a terminal, starting the agent, and letting it work on your current branch. This works for a single task. But as an operator, your goal is to have multiple tasks moving at once.

The moment you open a second terminal and try to run another agent in the same directory, you hit a wall. Git is designed to protect the integrity of the repository, which means it locks the index during writes. If Agent A is mid-commit or mid-stage, Agent B will fail. Even if you manage to avoid the lock, having two agents modifying the same working directory is a recipe for chaos. They will delete each other's temporary files, get confused by unexpected state changes, and eventually produce a merge conflict that requires twenty minutes of human intervention to fix.

I found through trial that you cannot treat an agent like a human developer who "knows" what else is happening in the room. You have to give the agent its own room.

Why Worktrees are the Answer

Git worktrees allow you to have multiple branches checked out simultaneously in separate directories while sharing the same .git history. Unlike a simple git clone, worktrees are linked to the main repository. This means you don't have to manage multiple copies of your dependencies or re-download gigabytes of history.

For claude-code-workflows, worktrees provide the necessary isolation. Each agent gets its own directory, its own index, and its own HEAD. They can run git add, git commit, and git reset as much as they want without ever seeing the other agents.

The Agent-Worktree Script Architecture

I use a script to automate the creation and destruction of these agent environments. The goal is to make spawning an agent as cheap as opening a new tab.

Step 1: Isolation

The script starts by creating a new directory outside of your main working path. I typically keep an agents/ folder in my project root (ignored by git).

``bash git worktree add -b agent-task-xyz ./agents/task-xyz main ``

This command does three things: it creates a new branch (agent-task-xyz), creates a new directory (./agents/task-xyz), and checks out that branch into that directory.

Step 2: Context Injection

Before starting Claude Code, the script copies in any necessary local context that isn't tracked by git—usually .env files or local configuration overrides. This ensures the agent has a functional environment to run tests or build the project.

Step 3: The Ephemeral Lifecycle

The script then initializes the Claude Code session within that specific directory. I pass the initial task description directly to the agent so it can start working immediately.

``bash cd ./agents/task-xyz && claude-code "Implement the new billing logic..." ``

Once the agent signals it is done, the script doesn't just leave the worktree there. It waits for my signal to review.