I had cut a branch by hand to fix a small bug in the Android build of my wallpaper app, then opened the Code tab in Desktop. The fix itself took a few lines. But when I asked for a build, it stopped with an error saying a config file couldn't be found.
The file was right there on my machine. It took me a while of staring at two windows to notice that the session wasn't running on my branch at all. It was running in a separate checkout under .claude/worktrees/, and the config file I keep in .gitignore had never existed there.
Other people have hit the same confusion. A Claude Code issue reports that every new Desktop session starts with the Worktree toggle already checked (#110975, still open as of November 18). Meanwhile, the official docs say Worktree is off by default. Here is how I worked through that gap, in the order I'd suggest.
Three signs you're actually in a worktree
Before touching any settings, confirm that a worktree is really involved. If you start changing things based on a hunch, you take the long way around, as I did.
- A new folder appears under
.claude/worktrees/<name>/in your project git branchlists branches you don't remember creating, starting withclaude/or with whatever Branch prefix you set in Settings- Running
pwdinside the session returns a path that contains.claude/worktrees/
The third one is the most reliable. Use the terminal pane in Desktop, or simply ask the session to run pwd and git branch --show-current.
# One-line check: is this session inside a worktree?
[ "$(git rev-parse --absolute-git-dir)" = "$(git rev-parse --path-format=absolute --git-common-dir)" ] \
&& echo "main checkout" || echo "inside a worktree: $(git rev-parse --show-toplevel)"A linked worktree has its own .git directory, separate from the .git it shares with the main checkout. Comparing the two tells you the answer without relying on folder names.
Off by default, yet on every time: three places to look
According to the docs, Worktree is something you choose before a session starts, and it's off by default. If it keeps coming up on, some setting somewhere is making "on" the default. This is the order I searched in.
| Order | Where to look | Why it ends up on | Fix |
|---|---|---|---|
| 1 | The row under the prompt box (current layout) | The Worktree button is on when you start the session | Turn the button off before you send (you can't switch once the session starts) |
| 2 | Saved environments in the environment selector (gear icon) | A saved local or SSH environment has Worktree recorded as its default | Edit the environment and turn Worktree off, or start from a different environment |
| 3 | The checkbox next to the branch name (earlier layout) | Without an environment selector, this checkbox is the Worktree switch | Uncheck it, and consider moving to the current layout |
For me, it was the second one. I had created a saved environment for parallel work a while back, left Worktree on, and kept starting sessions from it. A default you set once is very easy to forget you ever set.
The easiest ones to miss are saved environments you never created yourself. The docs say that the first time you open the Code tab in the current layout, Desktop creates up to eight environments from the local and SSH folders you used most in the past month. If your selector shows environments you don't recognize, open each one from its gear icon and check what's inside.
What issue #110975 asks for is a persistent setting for whether new sessions use worktrees. Per-environment defaults already exist, but I couldn't find a global setting that applies to every new session in the docs as of November 21.
When to let it create one, and when to skip it
Worktrees aren't the villain here. They exist so that several sessions on the same repository don't step on each other's edits. The only problem is getting one when you don't need it.
| Situation | Worktree | Why |
|---|---|---|
| Running two or more sessions on the same repository at once | On | Edits never land on the same files |
| Handing off an experiment whose outcome you can't predict | On | Throwing it away doesn't touch the main checkout |
| You already cut a working branch yourself | Off | The branch is your isolation; a worktree just adds a merge step |
| The project needs gitignored files like .env or local.properties to run | Off, or on after adding .worktreeinclude | A worktree is a fresh checkout, so untracked files aren't there |
| Working over SSH on a connection that drops often | Consider off | In a worktree session, Desktop checks each edit, and edits can fail while disconnected |
One layer of isolation is enough. If you've branched, you don't need a worktree. That's the line I keep now. On days when I hand something off without branching first, I let the worktree do the job, and cleaning up the main checkout afterward gets easier.
To bring gitignored files into worktrees, put a .worktreeinclude file at the project root. It uses .gitignore syntax, and only files that match a pattern and are also gitignored get copied.
.env
.env.local
local.propertiesA SessionStart hook so you notice even when it's on
Even if you choose carefully every time, slips happen. So I added a hook that prints one line only when a session starts inside a worktree. The goal is to skip the "why is this file missing?" detour I described at the top.
#!/usr/bin/env python3
"""SessionStart hook: tell the user and Claude when a session starts inside a worktree."""
import json
import os
import subprocess
import sys
def git(cwd, *args):
r = subprocess.run(["git", "-C", cwd, *args], capture_output=True, text=True)
return r.stdout.strip() if r.returncode == 0 else ""
def main():
try:
data = json.load(sys.stdin)
except json.JSONDecodeError:
return 0 # never block the session just because the input was unreadable
# In a Desktop worktree session, hooks run at the main checkout's root,
# so read the worktree path from the input's cwd, not os.getcwd() or CLAUDE_PROJECT_DIR
cwd = data.get("cwd") or os.getcwd()
git_dir = git(cwd, "rev-parse", "--absolute-git-dir")
common = git(cwd, "rev-parse", "--path-format=absolute", "--git-common-dir")
if not git_dir or git_dir == common:
return 0 # not a git repo, or the main checkout: stay quiet
top = git(cwd, "rev-parse", "--show-toplevel")
branch = git(cwd, "branch", "--show-current") or "(detached)"
main_root = os.path.dirname(common)
missing = [f for f in (".env", ".env.local", "local.properties")
if os.path.exists(os.path.join(main_root, f))
and not os.path.exists(os.path.join(top, f))]
msg = f"Running in a worktree: {top} (branch {branch})"
if missing:
msg += f" / in the main checkout but missing here: {', '.join(missing)} (check .worktreeinclude)"
print(json.dumps({
"systemMessage": msg,
"hookSpecificOutput": {
"hookEventName": "SessionStart",
"additionalContext": msg + ". If a build or test fails, suspect this difference first.",
},
}))
return 0
if __name__ == "__main__":
sys.exit(main())Save it as .claude/hooks/worktree-notice.py and register it in the project's .claude/settings.json.
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/worktree-notice.py\""
}
]
}
]
}
}Three choices are worth explaining.
- It reads
cwdfrom the input. In a worktree session started from Desktop, hooks run at the main checkout's root, andCLAUDE_PROJECT_DIRpoints there too. The worktree you're actually working in only shows up in thecwdfield of the JSON passed to the hook. Useos.getcwd()instead and it will always say "main checkout" - It returns both
systemMessageandadditionalContext. The first is the line you see on screen; the second is context Claude reads before its first reply. You and Claude start from the same picture - It fails quietly. Outside a git repo, or with malformed input, it prints nothing and exits 0. A hook meant to inform you shouldn't be the thing that stops your session
I checked it with git 2.34.1 by piping JSON for three cases: inside a worktree, in the main checkout, and outside git. Only the worktree case prints a line, and when .env exists in the main checkout but not in the worktree, the hook names it.
If it still keeps happening
If you've gone through all of the above and still can't find what's turning it on, here's what I'd do next.
- Start from the CLI. Launching
claudein a terminal never creates a worktree unless you pass--worktree(-w). For urgent work, this was the most reliable escape hatch for me - Add your details to issue #110975. Mention whether you use local or SSH, which layout you have, and whether you start from a saved environment. Those details help with reproduction, and even a 👍 feeds into prioritization
- Clean up stray worktrees by archiving. Uncommitted changes can be lost when a session is archived, so commit anything you want to keep first, then choose Archive from the session's menu in the sidebar. For local sessions, Desktop removes leftover worktrees, changes included, about 30 days later
If you want to take stock of accumulated worktrees before deleting anything, I wrote up a read-only inventory in Taking Inventory of Worktrees That Were Supposed to Be Gone. For the parallel-sessions side of the design, my implementation notes on running Claude Code per worktree are a good starting point.
Next time you start a new session in Desktop, glance at the row under the prompt box once before you send. If Worktree is on, ask yourself whether this session really needs isolation. Since I started taking that one breath as an indie developer juggling a few repos, I haven't spent another evening deleting branches I didn't recognize.