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 listShows 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 pruneAuto-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:
noodle worktree exec <name> <cmd>— CWD-safe by design- Subshells:
(cd /path && cmd)— CWD resets when subshell exits - Absolute paths:
go build /path/to/pkg/... - Tool flags:
git -C <path>,go -C <path>
Parallel Agent Teams
- Lead creates one worktree per teammate:
noodle worktree create phase-1 - Spawn each with
mode: "acceptEdits"— worktrees are isolated scratch space - Each teammate commits on its own branch
- 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-workFoundational 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:
- Merged (shows "safe to clean up") ->
noodle worktree cleanup <name> - Unmerged with commits -> report to user, let them decide merge vs discard
- No commits -> crashed session artifact ->
noodle worktree cleanup <name>