Experience using it with VisualStudio Code

[acs]

Before having this extension, I was storing the worktrees in a folder outside the root folder of VS Code workspace. And add the worktrees flder manually to the project workspace. I have issues in this scenario because SpecKit in one chat session started using the spec context from another chat session. Passing the spec data as a env param to the agent commands was enough and it mostly worked.

With this extension, worktrees are now stored inside the root folder of the VS Code workspace and it is not reliable. In a chat sessions, the agent ends using normally the main repository, not the worktree one, and I need to recheck constantly that the worktree is used.

Probably the main issue is that a VS Code workspace is not designed to work with different repositories (worktrees). The AI recommended me to open a new VS Code per worktree, but in this scenario, I loss the ability to manage chat sessions from a central point.

Do you have any recommendations? I suspect that for work in parallel with different specs. maybe OpenCode CLI could be a better option.

[dango85]

Thanks for the clear write-up.

There are two different failure modes that often feel like one bug:

1. Spec / .specify mix-up — The assistant picks up instructions or paths from the wrong root (e.g. another worktree or the main checkout). Symptom: wrong plan.md, wrong .specify scripts, or answers that don’t match the branch you care about—even before you run any terminal command.

2. Repo / cwd mix-up — The chat’s reasoning might be fine, but the default working directory for the agent, tasks, or integrated terminal is still the main repo. Symptom: edits and git commands land in the wrong worktree even when the spec you talked about was correct.

Multi-root workspaces still often behave like there is one primary folder, so several worktrees in one window stays fragile unless you pin the worktree path and spec context (env vars, explicit paths, dedicated terminal cd) for that session.

What usually works: one window per active worktree (most reliable), or stay multi-root but keep explicit worktree + spec paths / env and one terminal per worktree with the right cd. A CLI in separate terminals is often predictable for parallel work because cwd and env are obvious.

We’re open to product/docs improvements (e.g. recommended “open folder = worktree root”, or an active-worktree mechanism). If others have a workflow that stays stable—especially multi-root or worktrees inside the repo—please share concrete steps so we can turn patterns into guidance or features.

[acs]

@dango85 thank you so much for the explanation. I have been playing around with workflows in VS Code, SpecKit and worktrees and as you said, the only robust option is to open a new VSC window per worktree but then, you need to jump between windows and you lost the global view on how the system is behaving. And it is pretty manual: you need to open the window in the correct worktree path and, once finished, return to the "main" window and clean the worktree from this root window. Pretty messy.

I have been researching a bit and probably using TLI tools like Claude Code and Open Code, could help. But it seems we need new tools like Orca to really have intuitive workflows based on worktrees. But this is a 1 month old project and you can not build your workflows around it yet.

I will continue trying to find the best VS Code workflows based on worktrees and when I have specific improvements for the SpecKit support, I will share it with you, guys!

Thanks for your work.

[acs]

I have been using the extension creating new windows for worktrees in VS Code and it works nice.

• You start the spec in the main window /speckit.specify
• Accept to create a new worktree for the spec, be sure that the spec work is already committed so it appears in the worktree and create a new window for the worktree. The spec is finished in the main window.
• From the new window with the worktree continue executing /speckit.plan and the rest of the steps
• Once you have finished the implementation, commit, push and pr
• Close the worktree window
• Return to the main window and ask to remove the worktree

In order to minimize collisions (all specs are started from the main window), probably the worktree must be created as a pre-hook for specify so the specify could be executed inside the worktree and we have more isolation.

Pains with this workflow:

• You need to manage several windows
• The chat session (context) for the worktree is lost (but you have the spec and related files which is the real memory)

[dango85]

Thanks again for the concrete workflow notes. I agree with the main point: the better isolation boundary is before the spec is written, not after /speckit.specify has already created artifacts in the primary checkout.

I added this as an explicit worktree-first command rather than a raw before_specify hook: /speckit.worktrees.specify.

The reason is that a before_specify hook can create a worktree, but unless Spec Kit also switches the active project root for the remainder of /speckit.specify, the command can still keep writing spec artifacts in the original checkout. The explicit command makes the sequence predictable:

1. Create or reuse the feature worktree first.
2. Treat that worktree path as the project root.
3. Write the spec under /specs//.
4. Continue plan/tasks/implementation/commit/PR work from that worktree.
5. Return to the primary checkout only for cleanup.

This is now documented in the README, and the command was added in PR #8: #8

The VS Code pain point remains real: one window per worktree is still the most reliable mode today, and chat context does not automatically follow between windows. But this gives the extension a clearer worktree-first workflow that avoids starting every spec in the main checkout.

[acs]

As reference, the link with the VSC worktree support: https://code.visualstudio.com/docs/sourcecontrol/branches-worktrees

Confirmed that the approach is to use different windows.

[dango85]

Good point on the VS Code handoff. I agree this can be improved at the extension level without needing to become a full VS Code extension.

The first step I’m proposing is a Level 1 handoff in /speckit.worktrees.specify: after the command creates or reuses the worktree, it can optionally hand that path to VS Code through the code CLI.

The proposed behavior is:

• keep one VS Code window per active worktree as the safe default
• support /speckit.worktrees.specify ... --open-vscode
• default to code -n
• allow explicit reuse with code -r only when configured/requested
• fall back to printing the exact command when the code CLI is unavailable
• make it configurable through worktree-config.yml

I opened a draft PR for that here: #9

This does not try to control VS Code internals or preserve chat context across windows, but it should remove the manual copy/open step and line up better with VS Code’s documented worktree model.

[acs]

Update: VS Code now has an Agents Window that natively supports worktrees.

https://code.visualstudio.com/docs/copilot/agents/agents-window

With this Agents first window it is not needed that SpecKit manages at all the worktrees creation.