Worktree Auto-Sync

A VSCode extension that keeps your workspace folder list continuously in sync with the repo's live git worktrees — zero clicks. A worktree appears as a workspace folder the moment it is created and disappears when it is destroyed, without a window reload or extension-host restart — so an open Claude Code panel, terminal, or editor keeps its state.

Why

Claude Code creates git worktrees constantly — one per agent instance (isolation: "worktree"), one per -w / --worktree session (they land in .claude/worktrees/), and you may also create one worktree per issue by hand. Inspecting them in VSCode is manual today:

• VSCode's built-in Git and every worktree extension require a Command Palette action to add a worktree to the workspace.
• The closest existing extension caches the worktree list for ~60 s, so a worktree created inside that window stays invisible even when you run its command.
• No extension auto-removes a worktree's workspace folder when the worktree is deleted.

Worktree Auto-Sync closes that gap: live, continuous, hands-off.

How it works

Additive sync model — workspace folder 0 is never touched.

• Workspace folder 0 = the main repo. It is pinned on activation and never mutated again. Every worktree folder is added/removed at index ≥ 1. Per VSCode's documented behavior, non-first-folder changes do not restart the extension host — this is what makes the sync reload-free.
• A poll loop runs git worktree list --porcelain every pollIntervalMs. The worktree list is always read fresh — never cached.
• A debounce gate holds a newly-seen worktree for debounceMs before adding it, so a worktree that appears and vanishes quickly never flickers into the UI.
• On removal, editor tabs whose file lives under the worktree are closed first — no ghost tabs.
• Managed folders are labelled with their branch name, with an · agent marker for entries under .claude/worktrees/.

User-added workspace folders that are not git worktrees are tracked separately and are never removed by the extension.

Settings

A worktree created externally appears within roughly pollIntervalMs + debounceMs of its creation, with no user action.

Claude Code workflow

Point worktreeAutoSync.roots at .claude/worktrees to mirror exactly the worktrees Claude Code agents create, and nothing else:

// .vscode/settings.json  (or your .code-workspace)
{
  "worktreeAutoSync.roots": [".claude/worktrees"],
}

Each agent worktree then shows up as its own workspace folder (labelled <branch> · agent) while the agent runs, and is removed — with its editor tabs closed — when the worktree is torn down.

Single-folder window caveat

The first folder added to a plain single-folder window triggers VSCode's one-time single-folder → multi-root transition, which does restart the extension host once. Every add/remove after that is reload-free.

To avoid even that one restart, open your project as a saved .code-workspace file (File → Save Workspace As…). A .code-workspace is already multi-root-capable, so adding worktree folders never restarts the host. The extension shows a one-time warning when it detects the single-folder case.

Commands

Development

npm install
npm run build      # bundle to dist/extension.js
npm test           # vitest unit tests
npm run typecheck  # tsc --noEmit

Press F5 in VSCode to launch an Extension Development Host with the extension loaded.

Acknowledgements

Worktree Auto-Sync owes a real debt to tmokmss/vscode-git-worktree-switcher. Its author, tmokmss, took on a problem we shared — surfacing a repo's git worktrees in VSCode without the window reload that wipes out an open Claude Code panel's and terminal's state — and shipped a thoughtful solution for it. Studying that extension mapped out the sharp edges of the VSCode workspace-folder API for us and showed which approaches do and don't survive an extension-host restart. That was a genuine head start, and we're grateful for it. Thank you, tmokmss.

To be exact about the relationship: we read vscode-git-worktree-switcher for reference only — no code from it is used here. The two are independent implementations.

Why we built fresh rather than forking. vscode-git-worktree-switcher is MIT-licensed, so a fork was entirely open to us; we chose not to, and the reason is design, not licensing. It is built on on-demand Command Palette actions over a ~60-second cache of the worktree list. Worktree Auto-Sync is built on a continuous, never-cached poll loop, a debounce gate, and a strictly additive folder model that pins workspace folder 0 and only ever mutates index ≥ 1. Those decisions run all the way down — worktree discovery, caching, when and how the workspace is mutated, and whether the user is in the loop at all differ in every case. A fork would have had to replace nearly everything it inherited, which would imply a shared lineage the code simply doesn't have. A clean, independently credited implementation is the honest representation: full credit to the original for the idea, and a separate codebase for a genuinely different design.

License

MIT © 116 Ideas, Inc.