You want one Claude session to fix the documentation while another adds a test at the same time. Start both in the same folder and they will edit the same files and get in each other’s way. You need a second working folder.
What a worktree is
A is another working folder of the same repository, on its own . The folders share history, but each has its own files.
claude --worktree docs-pass
Claude Code creates the folder .claude/worktrees/docs-pass/ on a new branch worktree-docs-pass and starts a session in it. The short form is claude -w docs-pass. That session’s edit tools do not touch your main folder, and its commands do not run there or point git at it.
One condition: you must have run claude in this repository at least once and accepted the folder trust prompt. Otherwise claude --worktree exits with an error.
What is shared and what is not
| 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. So the session in a second worktree will have to install dependencies first.
Preparing the project
1. Keep the worktrees folder out of git. Otherwise their contents show up in the 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/: that folder holds settings and skills you commit for the team.
2. Put the ignored files you need in .worktreeinclude. If the project needs .env to run, list it in a .worktreeinclude file at the repository root, and it is copied into every new worktree:
echo '.env' > .worktreeinclude
List only what is necessary: every worktree gets its own copy of every secret.
Which branch a worktree starts from
A new worktree branches off the main branch on the remote, not your local HEAD. Unpushed commits and work from your feature branch will not be in it. That is why step 1 ended with git push.
If you need to start from your local HEAD, add this to .claude/settings.local.json:
{ "worktree": { "baseRef": "head" } }
Without a remote, a worktree starts from your local HEAD anyway.
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 yourself: while a session is isolated in a worktree, Claude Code blocks its git commands that reach into the main folder. 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.
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. After merging, choose remove.
Quick check
A worktree session cannot see the commit you made an hour ago. Why?
Careful
Removing a worktree deletes its folder and branch along with everything you have not merged. Merge first, then remove — or choose keep. And remember: “Yes, and don’t ask again” for a shell command in a worktree session is usually saved to the main folder’s .claude/settings.local.json and applies across the whole repository, even after the worktree is gone. Several sessions at once also multiply token usage: give each one a single small task.
Practice in the terminal