git worktrees in VS Code: windows, workspaces, and search

VS Code creates and opens worktrees natively

The Source Control Repositories view is the surface. Open it from the Source Control view, select your repository, open the More Actions menu, and choose Worktrees, then Create Worktree. VS Code prompts for a branch and a location, creates the folder, and checks the branch out into it. Each worktree then appears as a separate repository in that same view.

Bring the gitignored files with it

A worktree is a fresh checkout, so as VS Code's own documentation puts it, "when you create a worktree, Git does not copy files that are excluded by .gitignore". That is why a new worktree starts and then immediately fails to reach a database: the .env is not there.

{
  "git.worktreeIncludeFiles": [
    ".env",
    ".env.local",
    "config/secrets.json"
  ]
}

Surfacing worktrees you did not create in the editor

This setting matters far more than it used to, because agents now create worktrees inside your repository. Claude Code puts them under .claude/worktrees/<name>/ by default, and a subagent can create one without you asking at all.

{
  "git.detectWorktrees": true,
  "git.detectWorktreesLimit": 50
}

With detection on, VS Code scans the repository for worktrees and lists them in the Source Control Repositories view, so an agent's branch shows up next to yours with its own diff. The limit caps how many it will scan; the default is 50, which is generous for a human and worth checking if you run a lot of subagents.

One window each, or a multi-root workspace

This is the decision that actually changes your day, and the native worktree commands do not make it for you. Both options exist; one is the default and one is a deliberate choice for a specific job.

{
  "folders": [
    { "path": "../app",        "name": "main" },
    { "path": "../app-auth",   "name": "auth" },
    { "path": "../app-search", "name": "search" }
  ],
  "settings": {
    "search.useIgnoreFiles": true
  }
}

Keeping search and the file watcher sane

Worktrees living inside the repository used to be a mistake people made. It is now the default for Claude Code, which puts them under .claude/worktrees/. That means the exclusion settings below have gone from a nice-to-have to something you configure on day one.

{
  "files.exclude":         { "**/.claude/worktrees": true },
  "search.exclude":        { "**/.claude/worktrees": true },
  "files.watcherExclude":  { "**/.claude/worktrees/**": true }
}

Comparing and migrating changes back

Two commands close the loop without leaving the editor. Right-click a changed file in the worktree and choose Compare with Workspace to see the difference side by side. Then Migrate Worktree Changes from the Command Palette merges the worktree's changes into the current workspace.

cd .claude/worktrees/feature-auth
git diff main...HEAD
git push -u origin worktree-feature-auth
gh pr create --fill

When the editor is the wrong surface

There are two different jobs here and VS Code is excellent at one of them. Editing code in a worktree is editing code in a folder, and everything works. Keeping track of four agents working in four worktrees is a monitoring problem, and windows are a poor monitor: you cannot see them all, they do not tell you which agent is blocked, and they show you a diff only once you have already switched to it.

Questions people ask

Keep reading