|
| 1 | +--- |
| 2 | +name: worktree |
| 3 | +description: >- |
| 4 | + Guides git worktree creation, management, and cleanup for parallel |
| 5 | + development workflows including EnterWorktree usage, .worktreeinclude |
| 6 | + setup, and worktree lifecycle. USE WHEN the user asks to "create a |
| 7 | + worktree", "work in a worktree", "set up parallel branches", "isolate |
| 8 | + my work", "clean up worktrees", "list worktrees", "enter worktree", |
| 9 | + "worktree include", or works with git worktree commands, EnterWorktree, |
| 10 | + or parallel development patterns. DO NOT USE for routine git branching |
| 11 | + or single-branch workflows. |
| 12 | +version: 0.1.0 |
| 13 | +allowed-tools: Bash, Read, Grep, Glob |
| 14 | +--- |
| 15 | + |
| 16 | +# Git Worktrees |
| 17 | + |
| 18 | +## Mental Model |
| 19 | + |
| 20 | +A git worktree is a parallel checkout of the same repository. One `.git` database, multiple working directories, each on a different branch. Think of it as having multiple monitors for code — same project, different contexts, simultaneously active. |
| 21 | + |
| 22 | +The key difference from branches: a branch is a pointer to a commit; a worktree is a full working directory with its own index and working tree. Switching branches requires stashing, committing, or discarding changes. Switching worktrees means walking to a different directory. |
| 23 | + |
| 24 | +Use worktrees when: |
| 25 | +- **Parallel features** — work on two features without context-switching overhead |
| 26 | +- **Safe experimentation** — try a risky refactor without touching the main checkout |
| 27 | +- **Code review** — review a PR in one worktree while continuing work in another |
| 28 | +- **Hotfixes** — address an urgent bug without stashing mid-feature work |
| 29 | +- **Agent isolation** — give Claude Code agents their own working directory to prevent file conflicts |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## Creating Worktrees |
| 34 | + |
| 35 | +### Primary: EnterWorktree Tool (In-Session) |
| 36 | + |
| 37 | +The fastest way to create a worktree during a Claude Code session. Call `EnterWorktree` with a descriptive name: |
| 38 | + |
| 39 | +``` |
| 40 | +EnterWorktree: feature-auth-oauth2 |
| 41 | +``` |
| 42 | + |
| 43 | +**Behavior:** |
| 44 | +- Creates worktree at `<repo>/.claude/worktrees/<name>/` |
| 45 | +- Branches from current HEAD |
| 46 | +- Auto-names the branch `worktree-<name>` |
| 47 | +- Session moves into the worktree directory |
| 48 | +- **Auto-cleanup:** If no changes are made, the worktree and branch are removed on session exit. If changes exist, Claude prompts to keep or remove. |
| 49 | + |
| 50 | +### CLI Flag: `--worktree` |
| 51 | + |
| 52 | +Start a new Claude Code session directly in a worktree: |
| 53 | + |
| 54 | +```bash |
| 55 | +# Named worktree |
| 56 | +claude --worktree feature-auth-oauth2 |
| 57 | + |
| 58 | +# Auto-generated name |
| 59 | +claude --worktree |
| 60 | + |
| 61 | +# Combined with tmux for background work |
| 62 | +claude --worktree feature-auth-oauth2 --tmux |
| 63 | +``` |
| 64 | + |
| 65 | +The worktree is created at `<repo>/.claude/worktrees/<name>/` with the same auto-cleanup behavior as `EnterWorktree`. |
| 66 | + |
| 67 | +### Manual: `git worktree add` |
| 68 | + |
| 69 | +For worktrees outside of Claude Code sessions, or when precise control over path and branch is needed: |
| 70 | + |
| 71 | +```bash |
| 72 | +# Create worktree with new branch |
| 73 | +git worktree add /path/to/worktree -b feature-branch-name |
| 74 | + |
| 75 | +# Create worktree tracking existing branch |
| 76 | +git worktree add /path/to/worktree existing-branch |
| 77 | +``` |
| 78 | + |
| 79 | +> **Deep dive:** See `references/manual-worktree-commands.md` for the full command reference with all flags, path conventions, and troubleshooting. |
| 80 | +
|
| 81 | +### Naming Conventions |
| 82 | + |
| 83 | +- **Kebab-case, descriptive:** `feature-auth-oauth2`, `bugfix-login-timeout`, `spike-new-db` |
| 84 | +- **Prefix with category:** `feature-`, `bugfix-`, `spike-`, `chore-` |
| 85 | +- **Claude Code auto-naming:** Branches created by `--worktree` or `EnterWorktree` are prefixed `worktree-` |
| 86 | + |
| 87 | +--- |
| 88 | + |
| 89 | +## Environment Setup |
| 90 | + |
| 91 | +### `.worktreeinclude` File |
| 92 | + |
| 93 | +New worktrees start with only tracked files. Environment files (`.env`, `.env.local`) are typically `.gitignore`-excluded and will be missing. The `.worktreeinclude` file solves this. |
| 94 | + |
| 95 | +Place at the project root. It lists `.gitignore`-excluded files that should be **copied into every new worktree** automatically: |
| 96 | + |
| 97 | +```gitignore |
| 98 | +.env |
| 99 | +.env.local |
| 100 | +.env.* |
| 101 | +**/.claude/settings.local.json |
| 102 | +``` |
| 103 | + |
| 104 | +**Rules:** |
| 105 | +- Uses `.gitignore` pattern syntax |
| 106 | +- Only files matching **both** `.worktreeinclude` and `.gitignore` are copied |
| 107 | +- Tracked files are never duplicated (they come from the checkout itself) |
| 108 | +- Commit `.worktreeinclude` to the repo so the team benefits |
| 109 | + |
| 110 | +**If `.worktreeinclude` doesn't exist:** Copy environment files manually after worktree creation, or create the file first. |
| 111 | + |
| 112 | +### Post-Creation Checklist |
| 113 | + |
| 114 | +After creating a worktree, the working directory needs initialization: |
| 115 | + |
| 116 | +1. **Install dependencies** — `npm install`, `uv sync`, `cargo build`, or whatever the project requires. Worktrees share the git database but not `node_modules/`, `.venv/`, or `target/`. |
| 117 | +2. **Run `/init`** — in a new Claude Code session within the worktree, run `/init` to orient Claude to the worktree context. |
| 118 | +3. **Verify the dev environment** — run the test suite or start the dev server to confirm everything works. |
| 119 | + |
| 120 | +--- |
| 121 | + |
| 122 | +## Managing Worktrees |
| 123 | + |
| 124 | +### Listing |
| 125 | + |
| 126 | +```bash |
| 127 | +git worktree list |
| 128 | +``` |
| 129 | + |
| 130 | +Output shows each worktree's path, HEAD commit, and branch: |
| 131 | + |
| 132 | +``` |
| 133 | +/workspaces/projects/CodeForge d2ba55e [main] |
| 134 | +/workspaces/projects/.worktrees/feature-a abc1234 [feature-a] |
| 135 | +``` |
| 136 | + |
| 137 | +### Switching Context |
| 138 | + |
| 139 | +Worktrees are directories. To switch context: |
| 140 | +- **Terminal:** Open a new terminal and `cd` to the worktree path |
| 141 | +- **VS Code Project Manager:** Worktrees in `.worktrees/` are auto-detected and tagged `"worktree"` — click to open |
| 142 | +- **Claude Code:** Start a new session with `claude --worktree <name>` or use `EnterWorktree` |
| 143 | + |
| 144 | +### Cleanup |
| 145 | + |
| 146 | +**Claude Code auto-cleanup:** |
| 147 | +- No changes → worktree and branch removed automatically on session exit |
| 148 | +- Changes exist → prompted to keep or remove |
| 149 | + |
| 150 | +**Manual cleanup** (confirm with user first — destructive): |
| 151 | + |
| 152 | +```bash |
| 153 | +# Remove a specific worktree |
| 154 | +git worktree remove /path/to/worktree |
| 155 | + |
| 156 | +# Force remove (discards uncommitted changes) |
| 157 | +git worktree remove --force /path/to/worktree |
| 158 | + |
| 159 | +# Clean up stale worktree references (after manual directory deletion) |
| 160 | +git worktree prune |
| 161 | +``` |
| 162 | + |
| 163 | +### Merging Work Back |
| 164 | + |
| 165 | +After completing work in a worktree: |
| 166 | + |
| 167 | +1. **Commit and push** the worktree branch |
| 168 | +2. **Create a PR** from the worktree branch to the target branch |
| 169 | +3. **After merge**, clean up: |
| 170 | + ```bash |
| 171 | + git worktree remove /path/to/worktree |
| 172 | + git branch -d worktree-feature-name # delete merged branch |
| 173 | + ``` |
| 174 | + |
| 175 | +Alternatively, merge locally: |
| 176 | +```bash |
| 177 | +# From the main checkout |
| 178 | +git merge feature-branch-name |
| 179 | +``` |
| 180 | + |
| 181 | +--- |
| 182 | + |
| 183 | +## CodeForge Integration |
| 184 | + |
| 185 | +### Project Manager Auto-Detection |
| 186 | + |
| 187 | +The `setup-projects.sh` script scans `.worktrees/` directories at depth 3. Worktrees are detected by checking for a `.git` **file** (not directory) containing a `gitdir:` pointer. Detected worktrees receive both `"git"` and `"worktree"` tags in VS Code Project Manager. |
| 188 | + |
| 189 | +### Agent Isolation |
| 190 | + |
| 191 | +Four CodeForge agents use `isolation: worktree` in their frontmatter — refactorer, test-writer, migrator, and doc-writer. When spawned via the `Task` tool, these agents automatically get their own worktree copy of the repository. The worktree is cleaned up after the agent finishes (removed if no changes; kept if changes exist). |
| 192 | + |
| 193 | +### Workspace Scope Guard |
| 194 | + |
| 195 | +Each worktree is treated as an independent project directory by the workspace-scope-guard plugin. File operations are restricted to the worktree's directory boundary. |
| 196 | + |
| 197 | +### Path Conventions |
| 198 | + |
| 199 | +Two conventions coexist: |
| 200 | + |
| 201 | +| Convention | Path | Used by | |
| 202 | +|-----------|------|---------| |
| 203 | +| **Native (primary)** | `<repo>/.claude/worktrees/<name>/` | `--worktree` flag, `EnterWorktree` tool | |
| 204 | +| **Legacy** | `<container-dir>/.worktrees/<name>/` | Manual `git worktree add`, Project Manager detection | |
| 205 | + |
| 206 | +Native is recommended for Claude Code sessions. Legacy is used for manual worktree management and remains supported by `setup-projects.sh`. |
| 207 | + |
| 208 | +--- |
| 209 | + |
| 210 | +## Ambiguity Policy |
| 211 | + |
| 212 | +- Default to `EnterWorktree` for in-session worktree creation. |
| 213 | +- Default to the native path convention unless the user specifies otherwise. |
| 214 | +- When the purpose is unclear, ask: "What will you work on in the worktree?" |
| 215 | +- Default branch base: current branch HEAD, not main/master. |
| 216 | +- Default cleanup: prompt before removing worktrees with uncommitted changes. |
| 217 | +- When `.worktreeinclude` doesn't exist and the project has `.env` files, suggest creating one. |
| 218 | +- For agent work, defer to the `team` skill for orchestration — worktree isolation is automatic for agents that declare it. |
| 219 | + |
| 220 | +--- |
| 221 | + |
| 222 | +## Reference Files |
| 223 | + |
| 224 | +| File | Contents | |
| 225 | +|------|----------| |
| 226 | +| `references/manual-worktree-commands.md` | Full `git worktree` command reference with all flags, path conventions, `.git` file anatomy, and troubleshooting | |
| 227 | +| `references/parallel-workflow-patterns.md` | Workflow patterns for multi-worktree development, agent swarms, hooks, and anti-patterns | |
0 commit comments