Worktrees Fix Parallel Claude Code Sessions, Then Hand You Three New Problems

Running two Claude Code sessions in the same folder feels like double the speed. In practice it’s the slowest setup you can pick. The sessions overwrite each other’s untracked files, your test runners race, and you get merge conflicts before you’ve even looked at a diff. Worse, the failures look random. A test passes, then fails, then passes again, and you burn twenty minutes blaming the code when the real cause is two agents stepping on the same files.

The usual fix is Git worktrees. Each session gets its own directory and its own branch. That solves the file collision problem. But it also creates three quieter problems that can eat a whole afternoon, according to a recent r/PromptEngineering guide.

The key idea

A worktree isolates your files. It does not isolate everything else the agent touches: where it starts, what paths it remembers, and which ports it grabs. Treat those three as part of the setup, not as afterthoughts. If you only do the git worktree add step, you’ve fixed about a third of the problem and created a false sense of safety for the rest.

Old way vs. new way

The old way: one repo, two terminals, both agents working in the same checkout. You hope they stay out of each other’s way. Sometimes they do. Then one agent runs a formatter across the whole project while the other is halfway through a refactor, and you’re picking through the wreckage.

The next step up: create a worktree with git worktree add ../feature-branch feature-branch, then launch Claude Code from the repo root and point it at the new folder. This looks right, but the agent often gets confused about relative paths and quietly edits files in your primary checkout. You only notice when git status on main shows changes you never made.

The better way: treat each worktree as its own small world. Start the agent inside it, keep its memory relative, and give it its own ports. Same tool, far fewer ghosts. The difference is small in terms of commands and large in terms of how often you end up debugging the setup instead of the feature.

Practical steps

1. 🌳 Create the worktree: git worktree add ../feature-branch feature-branch. Pick a naming pattern you can read at a glance, such as the repo name plus the branch, so you never have to guess which terminal belongs to which folder.
2. 📂 cd into that directory before you start the agent. Don’t launch from the root and aim at a subfolder. This is the fix for CWD scope confusion. A quick check is to ask the agent to run pwd and git branch --show-current as its first action. If either answer surprises you, stop and restart before it touches anything.
3. 🧭 Keep skills and memory notes on relative paths. If a note says /Users/name/repo/packages/api, the agent will happily read the main branch’s copy after you switch to /Users/name/repo-feature/packages/api. Store state inside the active worktree root, not in some global location. When you review your notes, search them for any string that starts with a leading slash or your home directory. Each hit is a future wrong-file bug.
4. 🔌 Randomize test ports with environment variables in your runner config. If two sessions both bind to 3000 or 5432, one gets an EADDRINUSE error and may decide your codebase is broken. It isn’t. It’s just a busy port. A simple pattern is to read PORT from the environment and set a different value per worktree in a local .env file. Dev servers, test databases, and mock APIs all count, so check each of them.

When you’re done with a branch, remove the worktree with git worktree remove ../feature-branch instead of deleting the folder by hand. Otherwise Git keeps a stale record, and git worktree prune becomes a chore you’ll forget about.

The author also mentions autoharness from tigerless-labs on GitHub, which keeps skill definitions local, relative and git-trackable per branch, with no background process locks. I haven’t tested it, so treat it as a pointer rather than a recommendation.

The part people skip: databases

The post ends by asking how people handle database migrations across branches, and one commenter had a clean answer. Give each worktree its own disposable database with credentials scoped to it. Then have your migration skill check the target database before applying anything. Relative file paths won’t isolate a database, because two worktrees can still point at the same one.

Here is why this matters. Say branch A adds a column and branch B renames a table. If both run migrations against one shared dev database, the schema ends up matching neither branch, and every test failure afterward is noise. A throwaway database per worktree, created from a seed script and dropped when you remove the worktree, keeps each branch honest. It also means you can break things freely without a cleanup session later.

Another commenter said they hit all three traps in a single week and thought their repo was haunted. The absolute path one took the longest to find. That tracks, because it fails silently. The agent reads a real file. It’s just the wrong one.

Your move

Open your current agent setup and check three things: where you launch from, whether any saved paths are absolute, and which ports your tests bind to. Fix them one at a time, and run a second session only after the first check passes. Then tell me how you handle migrations across branches. I’d like to steal your setup!

The Git Worktree guide for parallel Claude Code sessions: fixing path drift and shared state corruption
by u/Least_Arm3744 in PromptEngineering