---
name: worktree
description: >-
  Use for concurrent sessions, agent team isolation, or any work needing a separate branch.
  Critical for multi-agent workflows. Triggers: "worktree", "new worktree", "clean up worktrees",
  "need isolation", or when spawning agent teams.
---

# Worktree

**Default to linked-worktree isolation.** Multiple sessions often run concurrently. Setup costs ~30 seconds and prevents hours of merge pain.

## Valid Workspace Definition

- **Valid for significant or autonomous work**: linked checkout created via Skill(worktree) `create` (typically `.worktrees/<name>`)
- **Not valid by default**: primary checkout at repo root
- **Allowed exception**: interactive, single-agent, small changes can run in primary checkout when that is the deliberate choice

All operations use `noodle worktree` — it enforces CWD safety, correct sequencing, stash/rebase handling, and dep reinstall.

## Commands

### Preflight

```bash
noodle worktree list
```

Shows all worktrees with merge status. Run at session start to spot stale worktrees from crashed sessions.

### Create

```bash
noodle worktree create <name>
```

Creates worktree + branch at `.worktrees/<name>`, symlinks `.claude/settings.local.json`, auto-detects package manager, installs deps.

### Run commands inside a worktree

```bash
noodle worktree exec <name> <command...>
```

Runs the command inside the worktree via `cmd.Dir`. **The parent shell's CWD never changes** — this is the safe way to run builds, tests, or any tool that needs the worktree as CWD.

```bash
# Examples
noodle worktree exec my-feature go test ./...
noodle worktree exec my-feature go build ./...
```

For git operations, `git -C` also works and doesn't need `exec`:

```bash
git -C <project-root>/.worktrees/<name> status
git -C <project-root>/.worktrees/<name> add -A
git -C <project-root>/.worktrees/<name> commit -m "message"
```

File reads/edits use absolute paths directly — no `exec` needed.

### Merge

```bash
noodle worktree merge <name>
noodle worktree merge <name> --into <branch>
```

Single command does: CWD safety check -> stash worktree noise -> rebase onto target branch -> merge -> remove worktree -> delete branch -> prune -> reinstall deps. Refuses to run if CWD is inside the worktree or if root checkout is not on the target branch.

By default, the target is the integration branch, auto-detected from `origin/HEAD` (falls back to `main` if detection fails). Use `--into` to merge into any branch — the root checkout must be on that branch when you run the command.

If there are no commits to merge, it exits early and leaves the worktree/branch in place so you can decide whether to continue work or run cleanup.

Merges are serialized via lockfile (`.worktrees/.merge-lock`). If another merge is in progress, the command waits with short retry intervals (default timeout: 5 minutes) and then proceeds automatically. Stale locks from crashed processes are detected and cleaned up automatically.

### Prune merged/patch-equivalent worktrees

```bash
noodle worktree prune
```

Auto-cleans safe worktrees:
- no commits ahead of integration branch, or patch-equivalent commits only
- clean working tree (no uncommitted changes)
- removes stale `.worktrees/<name>` directories that are no longer real worktrees

### Clean up without merging

```bash
noodle worktree cleanup <name>
```

Warns if there are unmerged commits. Use `--force` to discard them.

## Critical Safety Rules

**NEVER `cd` into `.worktrees/`** — if the shell CWD is inside a worktree when it gets removed, the shell dies permanently (exit code 1, no recovery, session over). This applies to:

- Direct `cd /path/to/worktree && ...` in Bash tool calls
- Any command that changes CWD as a side effect

The Bash tool maintains a persistent shell — `cd` in one call persists to ALL future calls. A later `rm -rf` or `git worktree remove` on that path kills the shell instantly.

**Always use one of these instead:**
1. `noodle worktree exec <name> <cmd>` — CWD-safe by design
2. Subshells: `(cd /path && cmd)` — CWD resets when subshell exits
3. Absolute paths: `go build /path/to/pkg/...`
4. Tool flags: `git -C <path>`, `go -C <path>`

## Parallel Agent Teams

1. Lead creates one worktree per teammate: `noodle worktree create phase-1`
2. Spawn each with `mode: "acceptEdits"` — worktrees are isolated scratch space
3. Each teammate commits on its own branch
4. Lead merges each: `noodle worktree merge phase-1`

**Sub-agent hierarchies**: A lead agent working in its own worktree (branch `lead-work`) can spawn sub-agents with their own worktrees. Sub-agents merge back into the lead's branch, not main:

```bash
# Root checkout must be on the target branch
git checkout lead-work
noodle worktree merge sub-work --into lead-work
```

**Foundational changes**: If Phase 1 is a foundation later phases need, do it on main first, commit, then create parallel worktrees. Branches start from the commit they were created at.

**When not to use**: sequential tasks, read-only research, single-agent work with no concurrency risk.

## Conventions

- **Directory**: `.worktrees/` at project root (gitignored)
- **Naming**: `.worktrees/<branch-name>`
- **Branches are ephemeral** — merge back to main and delete when done
- **Brain vault is shared state** — never branch it. Teammates send results back to the lead.

## Stale Worktree Triage

Use `noodle worktree list` to check status, then:

1. **Merged** (shows "safe to clean up") -> `noodle worktree cleanup <name>`
2. **Unmerged with commits** -> report to user, let them decide merge vs discard
3. **No commits** -> crashed session artifact -> `noodle worktree cleanup <name>`