Using Git Worktrees

Using Git Worktrees

Why Worktrees

A worktree is a second checkout of the same repo in a separate directory. Each worktree has its own working tree and HEAD, but shares the git object store. This means:

• Subagents work in isolation — no interference with your main session
• You can switch tasks without stashing
• Parallel features develop independently
• Clean rollback: abandon the worktree, nothing pollutes main

When to Use

Use at the START of every feature or bug fix. Do NOT start implementation until a clean worktree exists or you've confirmed you're already in one.

Mandatory before:

• subagent-driven-development skill
• executing-plans skill
• Any work touching more than one file

The Process

Step 1: Detect Existing Isolation

First check — are you already isolated?

# Check if current directory is a worktree (not the main checkout)
git worktree list
pwd

If you're already in a worktree for this feature: proceed to Step 3 (verify clean baseline). If you're in the main checkout: proceed to Step 2.

Step 2: Create the Worktree

# Create worktree + new branch in one command
git worktree add ../worktrees/ -b feat/

# Examples:
git worktree add ../worktrees/stripe-billing -b feat/stripe-billing
git worktree add ../worktrees/fix-auth-bug -b fix/auth-token-expiry

The worktree is created at ../worktrees/ (sibling of the project root). If the project uses .claude/worktrees/, use that path instead:

git worktree add .claude/worktrees/ -b feat/

Step 3: Verify Clean Baseline

Move into the worktree and confirm it starts clean:

cd ../worktrees/   # or .claude/worktrees/
git status                        # Should show: "nothing to commit"
git log --oneline -3              # Confirm you branched from the right point

If status shows unexpected changes: something is wrong — investigate before proceeding.

Step 4: Run Project Setup

Install dependencies and confirm the baseline builds:

npm install          # or pip install -r requirements.txt / go mod download
npm run build        # Confirm baseline build passes BEFORE any changes
npm test             # Confirm baseline tests pass BEFORE any changes

If baseline build or tests fail: STOP. Fix the issue on main first, then recreate the worktree.

Step 5: Proceed with Work

Now development starts. The worktree is isolated, the baseline is confirmed clean.

Cleanup After Work Completes

After the branch is merged or abandoned:

# From the main checkout (not from inside the worktree)
git worktree remove ../worktrees/
git branch -d feat/   # Only after merge

Common Issues

| Issue | Fix | |-------|-----| | "already checked out" error | The branch exists in another worktree — use a different branch name | | Worktree has unexpected changes | Run git status to investigate; never force-remove with uncommitted work | | Setup script fails in worktree | Check for absolute paths in scripts; worktrees use different working directories | | Submodules not initialized | Run git submodule update --init --recursive in the new worktree |

Worktree vs Branch Checkout

| | git worktree | git checkout -b | |--|----------------|-------------------| | Main session disrupted | No | Yes | | Parallel work possible | Yes | No | | Independent node_modules | Yes (separate dir) | Shared | | Subagent isolation | Clean | Risk of contamination |

Always use worktrees for subagent work. The isolation is the point.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RBraga01
• Source: RBraga01/a-team
• License: MIT
• Homepage: https://rbraga01.github.io/a-team/

Install and usage instructions live in the source repository linked above.