Git Worktree Architecture

Git worktrees are the infrastructure that makes multi-instance development on a single repository safe. Without worktrees, two Claude instances editing the same repository will produce file conflicts — Instance A writes to src/App.tsx while Instance B is reading from the same file, and the result is corrupted state. Worktrees solve this by creating separate working directories that share the same git history but operate on different branches.

The setup is mechanical. From your repository root, create a worktree for each parallel task: git worktree add ../project-feature-a feature-a and git worktree add ../project-tests tests. Each worktree is a complete working directory with its own copy of the source files, on its own branch. Instance A runs in ../project-feature-a, Instance B runs in ../project-tests. Both see the same git history, but their file systems are completely independent.

The worktree lifecycle follows a simple pattern. Create the worktree before starting a parallel task. Run Claude Code from the worktree directory so it loads the correct project context. When the task is complete and the branch is merged, remove the worktree: git worktree remove ../project-feature-a. The branch persists in git history; the working directory is cleaned up.

Worktrees also solve the CLAUDE.md consistency problem for parallel work. Each worktree shares the same CLAUDE.md from the repository, so all instances operate under the same rules. But because each worktree is on a different branch, changes to CLAUDE.md in one worktree do not affect the others until the branches are merged. This means you can experiment with rule changes in a worktree without destabilizing other instances.

1. 1. Create Worktrees From the repo root: git worktree add ../project-feature-a -b feature-a and git worktree add ../project-fix-bug -b fix-bug. Each worktree gets its own directory and branch. Name directories clearly — you will have multiple terminal tabs pointing at different worktrees.
2. 2. Launch Instances Open a terminal in each worktree directory and run claude. Each instance loads the project CLAUDE.md and operates independently. Rename your terminal tabs to match the worktree purpose: "feature-a," "fix-bug," "tests."
3. 3. Work in Parallel Issue prompts to each instance independently. While one processes, review or prompt the other. The key discipline: never edit the same logical component in two worktrees simultaneously. File-level independence is guaranteed by worktrees. Logical-level independence is your responsibility.
4. 4. Merge and Clean Up When a task completes, merge the branch (via PR or locally) and remove the worktree: git worktree remove ../project-feature-a. Keep your worktree count low — remove finished worktrees promptly to avoid directory sprawl.