Claude Code Worktrees: How to Run Parallel AI Coding Sessions

If you've ever had Claude Code refactor a component while you wanted to simultaneously ask a second session to write tests for a different feature, you've hit the same wall every single-branch developer hits: one working directory can only be checked out to one branch at a time. Switch branches mid-task and you either stash your changes or lose your place entirely.

Git worktrees solve this. They let you check out multiple branches of the same repository into separate folders on disk, each with its own file state, while sharing the same underlying .git history. Claude Code added native worktree support, so you can now run several agent sessions — each on its own branch, in its own directory — without them ever touching the same files or stepping on each other's edits.

This guide walks through what worktrees actually do, how to set them up with Claude Code, and the configuration details (env files, databases, ports) that trip people up the first time.

What Git Worktrees Actually Solve

A traditional git workflow ties you to one working directory per repository. To work on two branches at once, your only options are:

• Stash and switch — save your changes, checkout the other branch, do your work, checkout back, pop the stash. Slow and error-prone with agent-generated changes in flight.
• Clone the repo again — a full second copy of the repository, doubling disk usage and requiring you to keep both clones' remotes in sync manually.

Worktrees give you a third option: multiple working directories that all point back to the same .git object store. Each worktree has its own branch and its own files, but commits, branches, and remotes are shared and stay synchronized automatically. A git fetch in one worktree updates the refs visible from every other worktree.

For Claude Code, this means each agent session gets:

• Its own branch — no branch-switching collisions
• Its own file state — one session's edits never appear in another's
• A shared git history — commits and branches are visible everywhere, so merging back is straightforward

Setting Up Your First Worktree with Claude Code

Claude Code has built-in worktree management, so you don't need to memorize raw git worktree syntax — though it helps to understand what's happening underneath.

1. Create a worktree for a new task

From your main Claude Code session, ask it to create a worktree, or run the underlying git command yourself:

bash# Claude Code will do this via its worktree tooling, or you can run it directly
git worktree add ../myapp-feature-auth -b feature/auth-refactor

This creates a new directory (../myapp-feature-auth) checked out to a new branch (feature/auth-refactor), sitting alongside your main project folder.

2. Start a second Claude Code session in that directory

bashcd ../myapp-feature-auth
claude

You now have two independent Claude Code sessions running: one in your main working directory, one in the worktree. Each can read, edit, and run commands in its own directory without any risk of overwriting the other's work.

3. Repeat for additional parallel tasks

bashgit worktree add ../myapp-bugfix-321 -b fix/issue-321
git worktree add ../myapp-docs-update -b docs/api-reference

Three worktrees, three branches, three Claude Code sessions — each isolated, all sharing the same git history.

4. List and clean up worktrees

Worktrees accumulate fast if you don't clean them up. Check what's active and remove what's done:

bashgit worktree list
git worktree remove ../myapp-feature-auth
git worktree prune

Configuration Gotchas: Env Files, Databases, and Ports

Worktrees are file-isolated by default, which means anything gitignored — .env files, local database files, build caches — does not carry over into a new worktree automatically. This is the most common source of "why doesn't my app run in this worktree" confusion.

Carrying over gitignored files

Create a .worktreeinclude file at your repo root listing patterns that should be copied into every new worktree:

.env
.env.local
.claude/settings.local.json

Claude Code reads this file when creating a new worktree and copies matching files across, so each session has working credentials and local config without you copying them by hand.

Isolating databases per worktree

If two parallel sessions both write to the same SQLite file or the same Postgres/MySQL database, you'll get silent data corruption or confusing test failures neither session caused. Give each worktree its own database:

If you're on Neon (as this project is), branching the database alongside the git branch is the cleanest pattern: one Neon branch per worktree keeps schema experiments and migrations fully isolated from your main branch's data.

Avoiding port conflicts

If each worktree runs its own dev server, they'll all try to bind the same port by default. Assign distinct ports per worktree, either in each .worktreeinclude-copied .env:

PORT=3001

or as an inline override when starting the dev server:

bashPORT=3002 npm run dev

A Practical Parallel Workflow

Here's a workflow pattern that works well once worktrees are set up:

bash# After merging feature/auth-refactor
git worktree remove ../myapp-feature-auth
git branch -d feature/auth-refactor

When Worktrees Are Worth the Setup — and When They're Not

Worktrees add real value when:

• You're running multiple genuinely independent Claude Code tasks and want to review or steer them concurrently instead of sequentially
• You need to keep a stable branch (say, a demo environment) checked out while actively developing on another
• You're doing exploratory work — trying two different implementation approaches on separate branches to compare before committing to one

They're overkill when:

• You're doing simple, sequential tasks where switching branches once in a while is not a bottleneck
• Your project has heavy, hard-to-duplicate local state (large local datasets, license-locked services) that isn't practical to isolate per worktree
• You're working solo on a small codebase where the coordination overhead of managing multiple sessions outweighs the parallelism gained

Key Takeaways

• Git worktrees let Claude Code run multiple sessions in parallel, each on its own branch and file state, while sharing one git history.
• Gitignored files (.env, local configs) don't carry over automatically — use a .worktreeinclude file to copy them into new worktrees.
• Databases and dev server ports need explicit per-worktree isolation to avoid silent collisions between parallel sessions.
• Worktrees pay off most when tasks are genuinely independent; they don't eliminate merge conflicts, just branch-switching friction.
• Clean up worktrees and branches after merging to keep your repo tidy — git worktree list, remove, and prune are your maintenance toolkit.

Next Steps

Parallel AI workflows are exactly the kind of hands-on skill the Claude Certified Architect (CCA) practice tests are built to reinforce — real Claude Code patterns, not just theory. If you're preparing for certification or just want to sharpen your day-to-day Claude Code workflow, explore our free study guides and practice questions to build hands-on fluency before exam day.