# Worktree > 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. - Skill: `poteto/worktree` (Agent Skill) - Install (CLI): `npx skillmds add poteto/worktree` - Raw SKILL.md: https://api.skillmd.com/api/skills/poteto/worktree/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: poteto (https://skillmd.com/u/poteto) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/poteto/worktree --- # 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/`) - **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 ``` Creates worktree + branch at `.worktrees/`, symlinks `.claude/settings.local.json`, auto-detects package manager, installs deps. ### Run commands inside a worktree ```bash noodle worktree exec ``` 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 /.worktrees/ status git -C /.worktrees/ add -A git -C /.worktrees/ commit -m "message" ``` File reads/edits use absolute paths directly — no `exec` needed. ### Merge ```bash noodle worktree merge noodle worktree merge --into ``` 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/` directories that are no longer real worktrees ### Clean up without merging ```bash noodle worktree cleanup ``` 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 ` — 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 `, `go -C ` ## 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/` - **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 ` 2. **Unmerged with commits** -> report to user, let them decide merge vs discard 3. **No commits** -> crashed session artifact -> `noodle worktree cleanup `