◉CLAUDE LABJP
●CC 2.1.330 — Claude Code 2.1.330 fixes the multi-minute freeze right after compacting a long conversation●SONNET 4.5 — Sonnet 4.5 retires from the Claude API on 11/30, 8 days left. The suggested replacement is claude-sonnet-5-5●MCP 401 — Users report MCP servers that return 401 time out silently instead of showing an error●NEW — New: Desktop creates a worktree for every session? Three places to check●OPUS 4.5 — The 11/24 date for Opus 4.5 is a not-sooner-than floor, not a retirement notice●SCHEMA — Same schema, different shape: compare structured output from the Agent SDK and the Messages API●CC 2.1.330 — Claude Code 2.1.330 fixes the multi-minute freeze right after compacting a long conversation●SONNET 4.5 — Sonnet 4.5 retires from the Claude API on 11/30, 8 days left. The suggested replacement is claude-sonnet-5-5●MCP 401 — Users report MCP servers that return 401 time out silently instead of showing an error●NEW — New: Desktop creates a worktree for every session? Three places to check●OPUS 4.5 — The 11/24 date for Opus 4.5 is a not-sooner-than floor, not a retirement notice●SCHEMA — Same schema, different shape: compare structured output from the Agent SDK and the Messages API
Articles/Claude Code
⟐ Claude Code/2026-11-21Beginner

When Every New Desktop Session Creates a Worktree: Three Places to Check, and When It's Fine to Turn It Off

Claude Code Desktop keeps creating a worktree for every new session, and .claude/worktrees/ and claude/ branches pile up. Here is where the Worktree default actually gets turned on, when to keep it and when to skip it, and a SessionStart hook that tells you when a session is running inside a worktree.

Claude Code290Claude Desktop5git worktreeTroubleshooting28Hooks9

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 branch lists branches you don't remember creating, starting with claude/ or with whatever Branch prefix you set in Settings
  • Running pwd inside 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.

OrderWhere to lookWhy it ends up onFix
1The row under the prompt box (current layout)The Worktree button is on when you start the sessionTurn the button off before you send (you can't switch once the session starts)
2Saved environments in the environment selector (gear icon)A saved local or SSH environment has Worktree recorded as its defaultEdit the environment and turn Worktree off, or start from a different environment
3The checkbox next to the branch name (earlier layout)Without an environment selector, this checkbox is the Worktree switchUncheck 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.

SituationWorktreeWhy
Running two or more sessions on the same repository at onceOnEdits never land on the same files
Handing off an experiment whose outcome you can't predictOnThrowing it away doesn't touch the main checkout
You already cut a working branch yourselfOffThe branch is your isolation; a worktree just adds a merge step
The project needs gitignored files like .env or local.properties to runOff, or on after adding .worktreeincludeA worktree is a fresh checkout, so untracked files aren't there
Working over SSH on a connection that drops oftenConsider offIn 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.properties

A 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 cwd from the input. In a worktree session started from Desktop, hooks run at the main checkout's root, and CLAUDE_PROJECT_DIR points there too. The worktree you're actually working in only shows up in the cwd field of the JSON passed to the hook. Use os.getcwd() instead and it will always say "main checkout"
  • It returns both systemMessage and additionalContext. 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.

  1. Start from the CLI. Launching claude in a terminal never creates a worktree unless you pass --worktree (-w). For urgent work, this was the most reliable escape hatch for me
  2. 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
  3. 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.

Share

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

If you found this article helpful, a small tip ($1.50) would mean a lot to us. Your support helps keep this site ad-free and covers server and hosting costs.

Related Articles

⟐ Claude Code2026-10-29
When Claude Overwrites a Huge CLAUDE.md: Find the Missing Headings, Restore Them, and Block the Next One
Claude Code 2.1.312 fixed a bug where Claude overwrote a very large CLAUDE.md after seeing only its start. Here is how to spot lost headings on older versions, restore with git, and block full rewrites with a Write hook.
⟐ Claude Code2026-10-23
When a Nightly claude -p Says MCP "Needs Authentication": Check Mac Sleep and the Keychain First
If an unattended claude -p run leaves "needs authentication" or MCP timeouts in the morning log, check whether the Mac slept or the login keychain was locked. What v2.1.307 changed, and what it still leaves to you.
⟐ Claude Code2026-10-18
I Added the allow Rule and the Prompt Still Appears — Reading Six Layers from /permissions
When an allow rule is in your settings and the same approval prompt keeps coming back, something else decided first. Starting from what /permissions shows, here are six layers you can verify against the official permissions docs: ask and deny precedence, where settings.local.json is read, Cowork's shell tool, and more.