Using Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Systematic directory selection + safety verification = reliable isolation.

Scope

This skill covers git worktree setup, lifecycle, and known limitations for rageatc-code-oss workflows. It does NOT cover process-level isolation (Docker sandboxes), CI/CD pipeline isolation, or worktree usage outside of chunk-based development.

When to Use

• Standard/Thorough workflows: Each implementation chunk gets its own worktree for isolation
• Parallel chunks (Thorough only): Multiple worktrees enable simultaneous work on chunks with non-overlapping file sets
• Quick workflow: Optional — branch-based isolation may suffice for single small changes

Approach: Orchestrator-Managed Worktrees

The orchestrator creates and manages worktrees manually using git worktree add, then points developer-agents to the worktree directory.

Why manual, not automated: Claude Code's isolation: "worktree" subagent frontmatter has critical open bugs (as of early 2026) — permission bypass doesn't work, and silent data loss on cleanup has been reported. The manual approach is reliable. See Known Limitations below.

Orchestrator:
  1. git worktree add <path> -b <branch>
  2. Run setup in worktree
  3. Launch developer-agent pointed at worktree path
  4. After review + accept: merge branch, remove worktree

Directory Selection

Follow this priority order:

1. Check Existing Directories

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

If found: Use that directory. If both exist, .worktrees wins.

2. Check CLAUDE.md

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If preference specified: Use it.

3. Ask User

If no directory exists and no CLAUDE.md preference:

No worktree directory found. Where should I create worktrees?

Recommended: .worktrees/ (project-local, hidden)

Safety Verification

Verify Directory is Ignored

MUST verify before creating any project-local worktree:

git check-ignore -q .worktrees 2>/dev/null

If NOT ignored:

1. Add .worktrees/ to .gitignore
2. Commit the change
3. Proceed with worktree creation

Why critical: Prevents accidentally committing worktree contents to repository.

Worktree Lifecycle

1. Create Worktree

# Name branch after chunk for traceability
git worktree add .worktrees/chunk-003 -b chunk-003/recipe-service

2. Run Project Setup

Auto-detect and run appropriate setup:

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

3. Verify Clean Baseline

Run tests to ensure worktree starts clean:

# Use project-appropriate command
npm test

If tests fail: Report failures, ask whether to proceed or investigate.

If tests pass: Worktree is ready for the developer-agent.

4. Assign to Developer

Orchestrator launches developer-agent with the worktree path as the working directory.

5. After Review + Accept

# Merge the chunk branch back to main
git checkout main
git merge chunk-003/recipe-service

# Clean up
git worktree remove .worktrees/chunk-003
git branch -d chunk-003/recipe-service

6. After Review + Reject (iteration cap reached)

# Discard the worktree — main is untouched
git worktree remove --force .worktrees/chunk-003
git branch -D chunk-003/recipe-service

Known Limitations

Subagent Permission Issues

Problem: Developer-agents running in worktrees via isolation: "worktree" subagent frontmatter may not be able to run bash commands (tests, git commit). The permissionMode: "bypassPermissions" flag is broken in this context (GitHub #29110, open as of early 2026).

Workaround: If the developer-agent reports BLOCKED due to permission issues:

1. Orchestrator reviews the agent's code output in the worktree
2. Orchestrator runs tests from the main session
3. Orchestrator commits from the main session

Silent Data Loss

Problem: Worktrees created via isolation: "worktree" can be silently deleted during cleanup, destroying uncommitted work with no warning.

Prevention: Always commit work before exiting a worktree session. The manual git worktree add approach avoids the auto-cleanup behaviour entirely.

Background Agents

background: true and isolation: "worktree" do not currently work together — background agents run in the main repository regardless of isolation setting.

Branch Naming

The isolation: "worktree" frontmatter generates opaque branch names (worktree-agent-{hash}). Manual worktree creation avoids this — name branches after chunks for traceability.

When to Use Worktrees vs Branches

Quick Reference

Red Flags

Never:

• Create worktree without verifying it's gitignored (project-local)
• Skip baseline test verification
• Use isolation: "worktree" with permissionMode: "bypassPermissions" (broken)
• Use isolation: "worktree" with background: true (ignored)
• Trust auto-cleanup — commit before exiting

Always:

• Follow directory priority: existing > CLAUDE.md > ask
• Name branches after chunks for traceability
• Verify clean test baseline before assigning to developer
• Merge to main only after review accepts

Evaluation Scenarios

1. Orchestrator needs to set up a worktree for chunk-003. Expected: checks for .worktrees/ directory, verifies it's gitignored, creates worktree with chunk-named branch, runs project setup, verifies tests pass, then assigns to developer-agent. Violation: using isolation: "worktree" frontmatter without awareness of permission bugs.

1. Developer-agent in a worktree reports BLOCKED — can't run bash commands. Expected: orchestrator runs tests from main session, reviews output, commits if tests pass. Violation: retrying the same agent invocation or abandoning the chunk.

1. Two chunks in the Thorough workflow have non-overlapping file sets. Expected: orchestrator creates two worktrees, launches developer-agents in parallel, merges each independently after review. Violation: running them sequentially when parallelism is safe.