When working on a repository with AI Agents, you often want multiple sessions running in parallel. One fixing a bug, another adding a new feature, and perhaps a third one refactoring tests.
But sharing the same working directory would be a nightmare. File changes from one session will collide with the changes from others, creating merge conflicts, and breaking things. Git worktrees solve this issue by giving each session its own isolated copy of the codebase, while sharing the same repository history.
Git worktrees is a built-in feature of Git which allows users to checkout multiple branches of the same repository simultaneously, each in its own separate directory.
Unlike cloning a repository multiple times, worktrees share the same .git data, which means they share commit history, remotes, and configuration - all without needing to store duplicates of the repository. This makes them both lightweight, and fast to create compared to full clones of the repository.
Fun fact: Git worktrees has been around as a built-in feature of Git since 2015, however, before AI assisted developments, developers primarily worked on one branch at a time, switching branches when needing to work on something else, making it a niche feature few used.
But with the advent of AI assisted development and improvements in AI tools such as Claude Code and Codex, worktrees are a necessary tool to achieve maximum efficiency during AI-assisted development.
Git worktrees are most valuable when you need parallel, independent work streams on the same repository, as they allow for:
Often, AI tools such as Claude Code and OpenAI Codex have built-in worktree support, however, because Git worktrees are a built-in feature of Git itself, you can set it up manually for any AI tool, even if there is no support built into your AI tool of choice.
With AI Agents with auto memory, such as Claude Code, as each worktree is a “separate working directory”, any memories gained will not be applied to the parent repository.
Claude Code has built-in worktree support via the --worktree flag (can also use -w). This creates an isolated worktree and starts a Claude session inside of that worktree automatically. The value that you pass in the command becomes the worktree directory and branch name, or if you leave it blank, generates one automatically for you.
# Start Claude in a worktree named "feature-auth"claude --worktree feature-auth# Start Claude in a worktree and auto-generate a nameclaude --worktree
Git worktrees in Claude Code are created at:
{{ REPO NAME }}/.claude/worktrees/{{ WORKTREE NAME }}
and branch from the default remote branch. When you exit a session, it does one of two things:
Claude Code's Subagents can also use Git worktree isolation by setting isolation:worktree inside of the agent's frontmatter. This gives each Subagent generated its own copy of the codebase to work in parallel without conflicts.
OpenAI Codex offers Git worktrees directly inside of its interface. When creating a new thread, you can select “Worktree” to start in an isolated environment.
Codex then creates the Git worktree in a deteached HEAD state that lets you either continue working in the worktree or hand off the changes to your local checkout when you're ready to inspect them.
For AI tools without built-in support for Git worktrees, you can still create worktrees manually and start your agent inside of them! You can do so by creating a worktree, and then starting your AI Agent inside of the worktree.
# Create a worktree for the taskgit worktree add ../my-project-feature -b feature-branch# Navigate and start your agentcd ../my-project-feature#Start your AI coding agent here (e.g. aider, copilot, cursor, etc...)# When done, clean upgit worktree remove ../my-project-feature
Git worktrees are fresh checkouts - they don't include files that have been added to .gitignore such as .env or node_modules/. For AI coding tools with built-in worktree support (like Claude Code), you can create a .worktreeinclude file in your project root to specify which Git ignored files should be copied into new worktrees:
.env.env.localconfig/secrets.json
For manual worktrees, remember to copy over necessary environment files and run your dependency installation (e.g. npm install, pip install) before starting your agent session.
AI Agents such as Claude Code and OpenAI Codex work by reading, editing, and creating files inside of your repository as they work. When you run a single session, this works without issue. However, in modern AI-assisted workflows increasingly involve parallel sessions with multiple agents working on independent tasks simultaneously.
When inside of an instance of your AI Agent (e.g. Claude Code), you can usually ask for work to be done in parallel using worktrees and your AI Agent will be able to do that for you, and then merge the changes back into your current working branch.
Without the isolation that Git worktrees provides, parallel sessions will most likely:
Without worktrees - Two Claude Code sessions share the same directory. Agent A is refactoring the auth module while Agent B is fixing a payment bug. Agent B's test run fails because Agent A just renamed a shared utility function mid-refactor.
❌ Figure: Bad example - Parallel sessions in the same directory cause unpredictable conflicts
With worktrees - Each session gets its own isolated copy of the code. Agent A refactors auth in worktrees/auth-refactor/, Agent B fixes payments in worktrees/payment-fix/. Both work independently and merge cleanly when done.
✅ Figure: Good example - Isolated worktrees let parallel sessions work without conflicts
Add .claude/worktrees/ (or your tool's worktree directory) to your .gitignore to prevent worktree contents from appearing as untracked files.