teebe › Guides › Claude Code worktrees

Claude Code worktrees: run parallel sessions without stepping on your main checkout

How claude --worktree works, how to run several sessions at once, and how to keep track of what each one touched.

A Claude Code worktree is a separate, isolated git checkout that Claude creates for a session so it can edit files, run commands, and make commits without touching your main working copy. It's built on plain git worktree, so the branch, the index, and the working files are all independent, even though the repo's history is shared. This is what makes it possible to run parallel Claude Code sessions on the same repo at the same time, each on its own branch, without one session's half-finished edit corrupting another's. This guide covers how to start one, run several in parallel, carry over your .env, and the one thing worktree mode doesn't give you: a way to see what each session actually did, which is what teebe is for.

Starting a session in a worktree

Run claude --worktree <name> (or the short form claude -w <name>) and Claude creates an isolated worktree and starts the session inside it. By default it lands at .claude/worktrees/<name>/ at the repo root, on a new branch named worktree-<name>. Leave off the name and Claude generates one for you, something like bright-running-fox.

You don't have to plan ahead either: mid-session you can ask Claude to "work in a worktree" and it uses its EnterWorktree tool to move there, with a matching ExitWorktree to leave. Once inside a worktree session, Claude Code also blocks file edits and commands aimed at your main checkout, so a session can't accidentally reach outside its own tree.

One setup step worth doing immediately: add .claude/worktrees/ to your .gitignore, or these directories start showing up as untracked clutter in your main checkout's git status.

Running several sessions in parallel

Open a second terminal, run claude --worktree <another-name>, and you have a second isolated session on its own branch, editing its own files, entirely independent of the first. This is the normal way to run parallel agents against the same repo: name each worktree for the task it's doing and you can have several Claude Code sessions going without any of them colliding.

The same isolation extends to subagents. Ask Claude to "use worktrees for your agents", or add isolation: worktree to a custom subagent's frontmatter, and that subagent gets its own worktree for the duration of its task. A subagent's worktree is removed automatically once it finishes without any changes left behind. The desktop app takes this further and gives every new session its own worktree automatically. For the full picture, see the official docs at code.claude.com/docs/en/worktrees.

Carrying your .env over

A worktree is a fresh checkout, which means anything gitignored, your .env, local certs, whatever, is simply absent from it. To fix that, add a .worktreeinclude file at your project root, written in gitignore syntax, listing the gitignored files you want copied into every new worktree. Claude copies them in automatically when the worktree is created.

Base branch and PR worktrees

By default, a new worktree branches from the remote default branch. The worktree.baseRef setting controls this: "fresh" (the default) branches from the remote default branch, "head" branches from your current local HEAD instead.

You can also hand Claude a pull request directly: claude --worktree "#1234" (or a GitHub PR or GitLab MR URL) creates a worktree checked out from that PR, at .claude/worktrees/pr-<number>. Passing the name of a worktree that already exists just reopens it, which is handy for picking a task back up.

Cleanup and resuming a session

What happens when you exit depends on the session. An interactive, unnamed session removes its worktree and branch automatically on exit, as long as the worktree is clean. A named session prompts you first. Either way, if the worktree has uncommitted changes or new commits, Claude always prompts you to keep or remove it rather than deciding for you.

Non-interactive -p runs skip cleanup entirely, so those worktrees pile up until you remove them yourself with git worktree remove (running git worktree unlock first if one is locked). Resuming a session later with --resume or --continue drops you right back into its worktree.

The blind spot: five sessions, five directories

Worktree mode solves isolation, but it doesn't solve visibility. Run five parallel Claude Code sessions and you end up with five separate .claude/worktrees/<name> directories, each on its own branch, each mid-edit. Nothing tells you which files each one has touched without cd-ing into every directory and running git status by hand, over and over, as the sessions keep working.

This is the gap teebe fills. It's a native macOS git worktree GUI that lists every worktree of every repo you add in one window, and it auto-detects the worktrees Claude Code creates under .claude/worktrees the moment they appear, no configuration needed. Files badge live the instant an agent edits them on disk, so you can watch several sessions at a glance instead of polling each one. Press Space on any changed file to peek its diff inline, and pin the window beside your terminal so it's always in view while the sessions run. See more on this in the Claude Code diff viewer guide, or check the full comparison of git worktree GUIs for Mac if you want to weigh alternatives.

The manual alternative

If you'd rather not use --worktree at all, plain git gets you the same isolation:

git worktree add ../repo-feature -b feature
cd ../repo-feature
claude

That's a worktree at a path you chose, on a branch you named, with Claude started inside it manually. It behaves the same as a Claude-managed worktree once you're in it, you just own the naming and the cleanup. For the full set of git worktree commands, see the git worktree cheat sheet, and if you're deciding whether a worktree or a plain branch switch fits your workflow, read git worktree vs branch.

Frequently asked questions

Where does Claude Code put worktrees?

By default at .claude/worktrees/<name> under your repo root, on a new branch named worktree-<name>. Add .claude/worktrees/ to your .gitignore.

Does Claude Code delete worktrees automatically?

For an interactive session, yes if it's clean: an unnamed session removes the worktree and branch on exit automatically, a named session prompts you first. If the worktree has changes or new commits, Claude always prompts. Non-interactive -p runs do not clean up, remove them yourself with git worktree remove.

Can subagents use their own worktree?

Yes. Ask Claude to use worktrees for its agents, or add isolation: worktree to a custom subagent's frontmatter. Subagent worktrees are removed automatically when the subagent finishes without changes.

How do I see what each parallel Claude Code session changed?

Each worktree is a separate directory, so by default you have to cd into it and run git status or git diff to check it, one at a time. A git worktree GUI like teebe lists every worktree under .claude/worktrees, badges files live as an agent edits them, and lets you peek any diff without leaving the window.

Free · open source · macOS 14+. Back to teebe.io →