What is a git worktree? (and why your coding agent created one)

What it actually is

A git worktree is a second working folder for the same project: same commit history, same remote, same .git data underneath, but its own checked-out branch and its own set of files on disk. Think of it less like a duplicate project and more like a hotel with one shared reservation system but several rooms: you can be checked into room 3 building the login page while another Claude Code session is checked into room 7 fixing a bug, and nobody’s suitcase spills into the other person’s room. Claude Code creates these “rooms” under .claude/worktrees/<name>/, each on a fresh branch like worktree-feature-auth.

Why your AI just did this

Claude Code reaches for a worktree whenever work needs to happen in an isolated copy of your files instead of your main checkout. That happens three ways. You can start one yourself with claude --worktree feature-auth (or the short -w feature-auth), which opens a fresh session in its own folder and branch. You can ask mid-session (“work in a worktree” or “isolate this from my other session”) and Claude calls a tool named EnterWorktree to set one up without you touching git directly. And it happens automatically for certain subagents: a custom subagent file with isolation: worktree in its header always gets its own worktree so it can refactor across many files without racing your main session’s edits. The desktop app goes further and puts every new session in its own worktree by default.

When you’ll run into it

• You run claude --worktree bugfix in a second terminal while your first session is mid-task, and a new folder shows up at .claude/worktrees/bugfix/ on a brand-new branch.
• You ask Claude to try two approaches at once, and it tells you it’s creating a worktree so the two attempts don’t collide on disk.
• You exit an interactive worktree session that has uncommitted changes, and Claude asks whether to keep the worktree (so you can return to it later) or remove it (deletes the folder and branch, plus anything uncommitted inside). A clean, unnamed session’s worktree is removed automatically without asking.
• You run a non-interactive job with -p --worktree ... and later find several stale folders sitting in .claude/worktrees/. Those never got the exit prompt, so nothing removed them.
• A brand-new worktree session can’t find your API keys, or npm install hasn’t run. A worktree is a fresh checkout, so anything gitignored like .env and anything installed like node_modules isn’t there unless you’ve set up a .worktreeinclude file or reinstalled.

What to check

• Add .claude/worktrees/ to your .gitignore. Otherwise every worktree folder shows up as untracked clutter in your main checkout’s git status.
• If a worktree session can’t see your secrets, create a .worktreeinclude file (same syntax as .gitignore) listing files like .env and .env.local so they copy into new worktrees automatically. Never commit those files themselves.
• Before removing a worktree, run git worktree list and check for uncommitted or unpushed work. Deleting one deletes its files and its branch for good.
• After a -p (non-interactive) worktree run, check .claude/worktrees/ for leftovers and clear them with git worktree remove <path> yourself.
• Remember a worktree still shares your repo’s .git history and saved permission approvals with your main checkout. It isolates files, not the whole project.

Say it like a dev

Instead of: “Can you build this without messing up what I’m doing in the other window?” Say: “Start this in its own worktree so it doesn’t touch my main session’s files.”

Instead of: “Why can’t this session see my API key?” Say: “This worktree is missing my .env. Should we add a .worktreeinclude so future worktrees carry it automatically?”

Instead of: “Clean up all those extra folders you made.” Say: “List the worktrees and remove any that don’t have uncommitted work in them.”