worktree · diff
git:20260702.8bdf8e7 to git:20260717.01e4a14
16 added, 66 removed. Audit B to B.
---
description: Creates a git worktree for isolated parallel development — new branch in a separate directory with project setup and test baseline. Enables multiple Claude Code sessions on different tasks simultaneously. Multi-repo aware. Use when you need to work on something else without disturbing current work.
disable-model-invocation: true
argument-hint: "[description]"
---
# Worktree
- Create a git worktree for isolated parallel development. Sets up a new branch in a separate directory (`.worktrees/`) with project setup and test baseline, so the main workspace stays on its original branch. Each worktree can host an independent Claude Code session.
+ Create a git worktree under `.worktrees/` on a new branch, with project setup and a test baseline. The main workspace stays on its original branch, so each worktree can host an independent Claude Code session.
## Workflow
- ### 1. Multi-repo Detection
+ ### 1. Target repo
- Read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` for workspace detection. If a multi-repo workspace is detected:
- - Run the git commands below inside the target child repo (the workspace root has no `.git/`, so git commands must target individual repos)
- - If the user specified a target repo (inline or in conversation), use it
- - If ambiguous, use `AskUserQuestion` — header "Target repo", question "Which repo should the worktree be created for?": list each repo as an option
+ If the current directory has no `.git/` directory, read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` and apply it. In a multi-repo workspace, run all git commands inside the target child repo: use the repo the user specified; if ambiguous, use `AskUserQuestion` — header "Target repo", question "Which repo should the worktree be created for?", one option per repo.
- ### 2. Worktree Detection Guard
+ ### 2. Detection guard
- Read `$CLAUDE_PLUGIN_ROOT/skills/worktree/references/worktree-setup.md` and run the **worktree detection guard** from that reference. If the guard detects you are already inside a linked worktree, inform the user:
+ Read `$CLAUDE_PLUGIN_ROOT/skills/worktree/references/worktree-setup.md` and run its **worktree detection guard**. If already inside a linked worktree, tell the user:
```
Already running inside a worktree (`<worktree-path>`).
To create another worktree, run this skill from the main workspace instead.
```
- Then **stop** — do not create recursive worktrees.
-
- ### 3. Gather Context and Branch Name
-
- Record the current branch:
-
- ```bash
- git rev-parse --abbrev-ref HEAD
- ```
-
- Determine a meaningful description for the branch from the **first source that provides enough signal** (check in this priority order):
-
- 1. **Inline description** — if the user provided text with the invocation (e.g., `/optimus:worktree "fix login timeout"`), use it directly
- 2. **Conversation context** — scan the current conversation for the user's task intent, problem description, or feature request
-
- If neither source provides enough signal, use `AskUserQuestion` — header "Worktree scope", question "What will you work on in the new worktree?":
- - **New feature** — "Implement a new capability"
- - **Bug fix** — "Fix a bug or issue"
- - **Other** — "Describe the task"
-
- If the answer captures only a category (New feature / Bug fix), follow up and ask for a few words describing the task — the slug needs a concrete description, not the category label.
-
- Read `$CLAUDE_PLUGIN_ROOT/skills/commit/references/branch-naming.md` for the naming convention. Determine `<type>` and generate the slug from the description.
+ Then stop — never create nested worktrees.
- **Handle collisions**: apply the **Collision Handling** section of the same reference.
+ ### 3. Branch
- Create the branch without switching to it:
+ Note the current branch as `<original-branch>`. Derive the task description from the invocation argument or the conversation; if neither gives enough signal, ask what the user will work on — follow up until you have a concrete description, not a category. Read `$CLAUDE_PLUGIN_ROOT/skills/commit/references/branch-naming.md` for the `<type>/<slug>` convention and collision handling, then create the branch without switching:
```bash
git branch <branch-name>
```
- ### 4. Create Worktree
-
- Follow the **setup procedure** from `$CLAUDE_PLUGIN_ROOT/skills/worktree/references/worktree-setup.md` using `<branch-name>` and `<original-branch>` from Step 3. The procedure handles:
- - Deriving the worktree directory name
- - Creating `.worktrees/` and ensuring it is gitignored
- - Creating the worktree: `git worktree add .worktrees/<worktree-dir> <branch-name>`
- - Running project setup in the worktree (npm install, pip install, cargo build, etc.)
- - Verifying the test baseline
+ ### 4. Create worktree
- On failure, follow the reference's **Failure handling** (§8) — cleanup and diagnostics — then stop.
+ Follow the **Setup** procedure from worktree-setup.md with `<branch-name>` and `<original-branch>`. On failure, follow its **Failure handling**, then stop.
- ### 5. Report and Next Steps
+ ### 5. Report
```
## Worktree Created
Working directory: `.worktrees/<worktree-dir>`
Branch: `<branch-name>` (from `<original-branch>`)
Main workspace: `<original-branch>` (unchanged)
Tests: passing / failing (pre-existing — N failures) / no test command detected
- ### Open the worktree
-
- **VSCode** (recommended — each worktree gets its own window, terminal, and file watchers):
- - Source Control panel → right-click the worktree → "Open Worktree in New Window"
- - Or from terminal: `code .worktrees/<worktree-dir>`
- - Or Command Palette → "Git: Open Worktree in New Window"
-
- **Claude Code CLI**: `cd .worktrees/<worktree-dir> && claude`
-
- ### Cleanup
-
- When done: `git worktree remove .worktrees/<worktree-dir>`
+ Open it: `code .worktrees/<worktree-dir>` (VSCode) or `cd .worktrees/<worktree-dir> && claude`
+ Cleanup when done: `git worktree remove .worktrees/<worktree-dir>`
```
- If the setup procedure's §3 modified `.gitignore`, add a line after "Main workspace": `.gitignore updated to ignore .worktrees/ (staged, not committed)`.
-
- In a multi-repo workspace, prefix all paths in the report with the target repo directory (e.g., `cd <repo>/.worktrees/<worktree-dir>`).
-
- Recommend running `/optimus:tdd` in the new worktree for test-driven development, or `/optimus:init` if the worktree needs project setup.
-
- Tell the user: **Tip:** for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.
+ If Setup modified `.gitignore`, add after "Main workspace": `.gitignore updated to ignore .worktrees/ (staged, not committed)`. In a multi-repo workspace, prefix all report paths with the target repo directory.
- ## Important
+ Never commit or push in the main workspace; it must end on `<original-branch>`.
- - Never commit or push anything in the main workspace
- - The main workspace branch is always restored to `<original-branch>`
- - Worktrees are created inside `.worktrees/` (gitignored) to keep the project root clean
+ Recommend starting a Claude Code session inside the new worktree to begin the work there.