worktree

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

noodle worktree list

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

Create

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

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.

# 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:

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

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

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

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:

# 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>