worktrees

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

---

Personal Prefs Across Worktrees

CLAUDE.local.md only exists in one worktree. To share personal preferences across all worktrees, use a home-directory import in each worktree's CLAUDE.local.md:

# CLAUDE.local.md
@~/.claude/my-project-instructions.md

This way all worktrees load the same personal preferences from a single source. The @~/... import syntax resolves to your home directory regardless of which worktree you're in.

---

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

Task	Command
Ensure .worktrees/ ignored	git check-ignore -q .worktrees/ || echo '.worktrees/' >> .gitignore
Create worktree	bd worktree create .worktrees/<name>
Create with branch	bd worktree create .worktrees/<name> --branch <branch>
List worktrees	bd worktree list
Remove worktree	bd worktree remove .worktrees/<name>
Check status	bd worktree info
Verify beads sync	bd ready (in worktree)

---

Why bd worktree?

Manual git worktree	bd worktree
Separate commands for git + beads	Single command
No beads redirect setup	Automatic redirect to main DB
No safety checks on remove	Checks for uncommitted/unpushed

---

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

Worktrees Share the Dolt Database

Worktrees created with bd worktree create share the main repo's Dolt database via .beads/redirect. This is the correct behavior — all worktrees see the same beads data.

If a worktree was created with git worktree add instead, it gets an independent empty Dolt DB. Fix by deleting the worktree's .beads/dolt/ and creating a .beads/redirect file pointing to the main repo's .beads/.

---

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 redirect setup and safety checks.