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

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:

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:

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

worktree

NPX Install

Tags

SKILL.md Content

Worktree

Valid Workspace Definition

Commands

Preflight

Create

Run commands inside a worktree

Merge

Prune merged/patch-equivalent worktrees

Clean up without merging

Critical Safety Rules

Parallel Agent Teams

Conventions

Stale Worktree Triage