// Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees following GitLens conventions
Use whenever any UI-bearing work touches a running instance — building or fixing a feature, ship-gating, auditing, OR debugging visible bugs (flaky behavior, intermittent rendering, "sometimes does X" reports, hover/focus/animation glitches, layout overflow). Keep a running instance in the loop and exercise it as a user would. Adaptive depth from tactical fix-loop to ship-gate audit. Not for pure-logic diff review.
Use for one-off / single-question inspection of the running GitLens extension — examining UI state, reading logs, checking feature flags, dispatching a command, or asking "what does the live DOM look like right now". Reference for `vscode-inspector` MCP primitives. For iterative debug-and-fix loops on UI bugs (sweep → fix → re-verify), use `/live-exercise` instead.
Investigate bugs — single-issue deep root cause analysis or batch parallel investigation from a report or issue list
Use when you want to iterate on a feature interactively with the user watching a running instance — pair-programming rhythm for UI-heavy work, redesigns, copy tightening, layout exploration, or any "let me just show you what I want" session. Not for systematic audit (/live-exercise) or perf-tuning (/live-perf).
Use when you want to measure and improve the performance of a feature in the running extension, hunt regressions, or perf-tune before shipping. Standalone for perf-tuning an existing feature; also invoked by /live-exercise Phase 7. Not for static code review without measurement.
Use to audit a component, file, or directory for WCAG 2.1 AA accessibility compliance. Detects ARIA anti-patterns, missing semantics, keyboard gaps, and color-only information. Safety-first — refuses to emit fixes that would create a new accessibility bug. Scope is always explicit; do not use for page-level flow or cross-program planning.
| name | worktree |
| description | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees following GitLens conventions |
This project uses a custom worktree convention: worktrees live in a sibling <repo-name>.worktrees/ directory (the layout the worktree.mts hook in .claude/settings.json is built around), not in the EnterWorktree default location.
Because of that, the flow has two steps:
git worktree add following the convention below (so it lands in the sibling .worktrees/ dir with the right name).EnterWorktree primitive with path. This moves the session's working directory into the worktree — a plain cd in Bash does not.Do not call
EnterWorktreewithnameto create the worktree. Inside a git repo it ignores the hook and places the worktree in.claude/worktrees/(which is not gitignored) on a branch offorigin/main, breaking this project's convention. Always create first, then enter bypath.
Worktrees live in a sibling directory to the main repo, named <repo-name>.worktrees/:
vscode-gitlens/ # Main repo
vscode-gitlens.worktrees/ # Worktrees root
├── debt/
│ ├── library/ # Branch: debt/library
│ ├── library+<session-id>+agent-x/ # Agent worktree from debt/library
│ └── refactor-home/ # Branch: debt/refactor-home
├── feature/
│ ├── ai-chat/ # Branch: feature/ai-chat
│ └── graph-actions/ # Branch: feature/graph-actions
└── bug/
└── graph-performance/ # Branch: bug/graph-performance
Agent worktrees use + delimiters: <branch>+<session-id>+<agent-name>. This keeps them as siblings to the parent worktree (not nested inside it), groups them by conversation session, and makes it easy to trace back to the originating session.
Branch path segments map directly to directory nesting (e.g., debt/library -> debt/library/).
Follow the conventions in AGENTS.md:
| Type | Prefix | Example |
|---|---|---|
| Feature | feature/ | feature/search-natural-language |
| Bug fix | bug/ | bug/graph-performance |
| Tech debt | debt/ | debt/library |
| With issue | include #N | feature/#1234-search-natural-language |
# 1. Find the worktrees root
REPO_ROOT=$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')
REPO_NAME=$(basename "$REPO_ROOT")
WORKTREES_ROOT="$REPO_ROOT/../$REPO_NAME.worktrees"
# 2. Create the worktree (branch path segments map to directory nesting)
git worktree add "$WORKTREES_ROOT/<type>/<name>" -b "<type>/<name>"
# 3. Install dependencies
pnpm install --dir "$WORKTREES_ROOT/<type>/<name>"
Then switch the session into it with the EnterWorktree primitive, passing the path you just created:
EnterWorktree({ path: "<absolute path to $WORKTREES_ROOT/<type>/<name>>" })
EnterWorktree requires an absolute path that already appears in git worktree list — which is why creation comes first. After this, all subsequent tool calls run inside the worktree.
When the work is done (or you need to return to the original repo), call ExitWorktree:
ExitWorktree({ action: "keep" })
Use action: "keep" — ExitWorktree will not remove a worktree that was entered by path (only ones it created via name), so keep is the correct, non-destructive choice here. The worktree and its branch stay on disk; remove them later with git worktree remove if needed.
.worktrees/ directory), not inside.gitignore verification needed — the directory is outside the repogit worktree add first, then enter via EnterWorktree({ path }) — never create with EnterWorktree({ name }) (it bypasses the convention)