Git Worktrees

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

Primary tool: bd worktree — handles git worktree + beads integration automatically.

When to Use

• Parallel subagents need filesystem isolation
• Feature work that shouldn't affect current workspace
• Separate builds/servers running simultaneously
• Before executing implementation plans

Guardrails

• Do not merge a worktree branch to main without explicit user sign-off — merges affect shared codebase and may contain unreviewed work
• Do not delete a worktree without explicit user sign-off — deletion destroys uncommitted changes
• Do not close beads for a worktree branch without user sign-off
• After completing implementation, stop and report status. Do not proceed to merge.
• Use /merge when ready to integrate — it enforces the pre-flight checklist.

Setup: Ensure .worktrees/ is Ignored

Before creating any worktrees, ensure .worktrees/ is in .gitignore. This is a one-time setup that covers all future worktrees:

# Check if .worktrees/ is already ignored
git check-ignore -q .worktrees/ || echo '.worktrees/' >> .gitignore

If you added the line, commit it:

git add .gitignore && git commit -m "Ignore .worktrees/ directory"

Why this matters: Without this, beads adds each worktree individually to .gitignore, creating noise. With .worktrees/ ignored, all worktrees underneath are automatically covered.

Creating a Worktree

All worktrees go under .worktrees/ in the repo root. This is the standard location.

bd worktree create .worktrees/feature-auth

What it does automatically:

1. Creates git worktree at the specified path
2. Sets up .beads/redirect pointing to main repo's database
3. Creates the branch (same name as the directory by default)

With custom branch name:

bd worktree create .worktrees/bugfix --branch fix-123

After Creation

1. Enter Worktree

cd .worktrees/feature-auth

2. Run Project Setup

# Node.js
[ -f package.json ] && npm install

# Rust
[ -f Cargo.toml ] && cargo build

# Go
[ -f go.mod ] && go mod download

3. Verify Baseline

npm test  # or cargo test, go test ./...

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

4. Verify Beads Shared

bd ready  # Should show same beads as main workspace

Listing Worktrees

bd worktree list

Or standard git:

git worktree list

Removing a Worktree

Use bd worktree remove — includes safety checks:

bd worktree remove feature-auth

Safety checks (automatic):

• Uncommitted changes
• Unpushed commits
• Stashes

Skip checks (not recommended):

bd worktree remove feature-auth --force

Worktree Info

Check current worktree status:

bd worktree info

Quick Reference

Why bd worktree?

Example Workflow

# One-time: ensure .worktrees/ is ignored
git check-ignore -q .worktrees/ || echo '.worktrees/' >> .gitignore

# Create isolated workspace
bd worktree create .worktrees/feature-auth

# Enter and setup
cd .worktrees/feature-auth
npm install
npm test  # ✓ 47 passing

# Verify beads shared
bd ready  # Shows same issues as main

# Work on feature...
bd claim auth-001

# When done
cd ../..
bd worktree remove .worktrees/feature-auth

Known Limitations

Daemon Mode

Daemon mode does not work correctly with user-created git worktrees. Worktrees share the same .git directory and beads database, but the daemon doesn't track which branch each worktree has checked out.

Solution: Use direct mode in worktrees:

bd --no-daemon <command>
# Or set environment variable
export BEADS_NO_DAEMON=1

Two Types of Worktrees

Don't confuse these:

The internal worktree is hidden and managed by beads for the sync-branch feature. Don't manually modify it.

SKIP_WORKTREE Issues

If git status doesn't show changes to .beads/*.jsonl files, check for SKIP_WORKTREE flags:

git ls-files -v .beads/
# 'h' prefix = SKIP_WORKTREE set (changes hidden)
# 'H' prefix = normal tracking

Fix: Remove and re-add the files:

git rm --cached .beads/issues.jsonl
git add .beads/issues.jsonl

Or run bd sync which sets the correct index flags.

Fallback (No Beads)

If beads isn't installed, use manual git worktree:

# Verify ignored
git check-ignore -q .worktrees/ || echo '.worktrees/' >> .gitignore

# Create
git worktree add .worktrees/feature-auth -b feature-auth

# Remove
git worktree remove .worktrees/feature-auth

But you lose: automatic gitignore, beads sync, and safety checks.