You want one Claude Code session to tidy the documentation while another writes a missing test. Start both in the same project folder and they edit the same files, run commands in the same place and step on each other’s work. The fix is not a smarter prompt. It is a second working folder.
This post is the first in a short series on the Claude Code: Pro Level course. It walks through the lesson on parallel sessions in worktrees: what a worktree is, what to prepare before the first run, and the one surprise that catches almost everyone.
What a worktree is
A worktree is another working folder of the same repository, checked out on its own branch. The folders share history, but each has its own files. Claude Code can create one for you and start a session inside it:
claude --worktree docs-pass
That command creates .claude/worktrees/docs-pass/ on a new branch called worktree-docs-pass and opens a session there. The short form is claude -w docs-pass. The session’s edit tools do not touch your main folder, and its commands do not run there.
One condition: you must have run plain claude in this repository at least once and accepted the folder trust prompt. If you have not, claude --worktree exits with an error.
What the copies share, and what each keeps
The mental model is simple once you see it as a table:
| Shared by all worktrees | Each worktree has its own |
|---|---|
| commits | uncommitted edits |
| branches | installed dependencies (node_modules) |
| history | files git ignores, such as .env |
Every worktree is a fresh checkout from git. That has a practical consequence: the session in a new worktree has to install dependencies before it can run anything. And anything git ignores — your .env, for example — is simply not there.
Two steps before your first parallel run
Keep the worktrees folder out of git
Without this, the contents of every worktree show up in your main folder as untracked files:
echo '.claude/worktrees/' >> .gitignore
git add .gitignore && git commit -m "Ignore Claude Code worktrees"
git push
Ignore exactly .claude/worktrees/, not the whole .claude/ folder. That folder also holds settings and skills you commit for your team.
List the ignored files you actually need
If the project needs .env to run, put it in a .worktreeinclude file at the repository root. Every new worktree then gets a copy:
echo '.env' > .worktreeinclude
Keep that list short. Every worktree gets its own copy of every secret you name there.
The trap: your fresh commit is missing
This is the part people lose an afternoon to. A new worktree does not branch off your local HEAD. It branches off the main branch on the remote. Commits you have not pushed, and work sitting on your feature branch, are not in it.
That is why the .gitignore step above ends with git push. If you really do need to start from your local state, add this to .claude/settings.local.json:
{ "worktree": { "baseRef": "head" } }
If the repository has no remote at all, a worktree starts from your local HEAD anyway.
Quick diagnosis
A worktree session cannot see the commit you made an hour ago? Check whether you pushed it. Nine times out of ten, that is the whole story.
Bringing the work back
Each session commits on its own branch. You do the merging, from the main folder, in a separate terminal:
git worktree list
git merge worktree-docs-pass
git merge worktree-test-pass
You merge it yourself because a session isolated in a worktree is not allowed to reach into the main folder: Claude Code blocks its git commands that point there. If both tasks changed the same lines, git stops at a conflict. Resolve it, or start claude in the main folder and ask for help with it.
Then type /exit in each session. If the worktree’s branch has new commits, Claude Code asks whether to keep the worktree or remove it. Once you have merged, choose remove.
Three things people regret
Removing a worktree deletes its folder and its branch, including anything you have not merged — merge first, or choose keep. Answering “Yes, and don’t ask again” to a shell command inside a worktree session usually saves that rule to the main folder’s .claude/settings.local.json, where it applies to the whole repository even after the worktree is gone. And every extra session spends its own tokens, so give each one a single small task.
When a worktree is the wrong tool
Worktrees solve one specific problem: two sessions that would otherwise edit the same folder at the same time. They do not make a task smaller or a plan clearer. If one session can do the job, one session is cheaper. If two tasks are going to rewrite the same lines anyway, you have only postponed the collision to merge time — split the work by files before you split it by folders.
Worktrees are also not the same as an agent team. The course’s agent teams lesson is explicit that teammates work in your shared working folder, not in separate worktrees, so two teammates editing one file will overwrite each other. Choosing between those patterns is the subject of the next post in this series.
Frequently asked questions
How is claude --worktree different from checking out another branch?
Checking out a branch switches the one folder you have. A worktree gives you a second folder on its own branch, so two sessions can work at the same time without touching each other’s files.
Where does the worktree live and what is its branch called?
claude --worktree docs-pass creates .claude/worktrees/docs-pass/ on a branch named worktree-docs-pass.
Why is there no .env in my new worktree?
Each worktree is a fresh checkout, and git does not track ignored files. List .env in a .worktreeinclude file at the repository root and it is copied into every new worktree.
Can the worktree session merge its own branch into main?
No. While a session is isolated in a worktree, Claude Code blocks its git commands that reach into the main folder. You merge from the main folder yourself.
Try it yourself
The worktree lesson has a practice terminal where you add the .gitignore rule, create .worktreeinclude and start a session in a docs-pass worktree. It runs in your browser, so you can rehearse the preparation before you try it on a real project.