Git Worktree Multi-Topic Development

Coordinate parallel development of multiple related features using git worktrees, a shared base branch, and manager/child Claude Code sessions.

Architecture

code

main (default branch)
  └── base/<project-name>  (base branch, created by manager)
        ├── <project-name>/topicA  (child branch → PR into base)
        ├── <project-name>/topicB  (child branch → PR into base)
        └── <project-name>/topicC  (child branch → PR into base)

worktrees/
  ├── <topicA>/  (worktree for topicA branch)
  ├── <topicB>/  (worktree for topicB branch)
  └── <topicC>/  (worktree for topicC branch)

Each topic gets its own worktree directory, its own branch, and its own PR targeting the base branch. The manager merges topic PRs into the base branch, then creates one root PR from base into main.

Roles

Manager Session (root repo)

The manager session operates from the repo root directory. It:

•Creates the base branch from main
•Creates worktrees for each topic
•Reviews and merges topic PRs into the base branch
•Creates the final root PR (base → main)

Child Sessions (worktree dirs)

Each child session operates from its own worktree directory. It:

•Implements its assigned topic
•Commits and pushes to its topic branch
•Creates a PR targeting the base branch
•Addresses review feedback from the manager

Manager Workflow

Step 1: Create Base Branch

bash

# Ensure main is up to date
git checkout main
git pull origin main

# Create and push the base branch
git checkout -b base/<project-name>
git push -u origin base/<project-name>

# Return to main
git checkout main

Step 2: Create Worktrees

For each topic:

bash

# Create worktree with a topic branch based on the base branch
git worktree add worktrees/<topic-name> -b <project-name>/<topic-name> base/<project-name>

Example with 3 topics:

bash

git worktree add worktrees/topicA -b marker-fix/topicA base/marker-fix
git worktree add worktrees/topicB -b marker-fix/topicB base/marker-fix
git worktree add worktrees/topicC -b marker-fix/topicC base/marker-fix

Step 3: Environment Setup (if needed)

If the project has environment files, symlink them into each worktree:

bash

for wt in worktrees/*/; do
  ln -sf "$(pwd)/.env" "$wt/.env" 2>/dev/null
  # Add project-specific symlinks as needed (e.g., metadata, generated files)
done

If using pnpm workspaces, install dependencies in each worktree:

bash

for wt in worktrees/*/; do
  (cd "$wt" && pnpm install)
done

Step 4: Launch Child Sessions

Tell the user to start a new Claude Code session in each worktree directory:

code

cd worktrees/<topic-name>
claude

Or use Claude Code teams with the Task tool to spawn child agents in each worktree.

Step 5: Review and Merge Topic PRs

As child sessions complete work and create PRs:

bash

# Review each topic PR
gh pr view <pr-number>
gh pr diff <pr-number>

# Merge topic PRs into base branch (regular merge, not squash)
gh pr merge <pr-number>

Step 6: Create Root PR

After all topics are merged into the base branch:

bash

# Create the root PR: base → main
gh pr create --base main --head base/<project-name> \
  --title "Root PR title" \
  --body "$(cat <<'EOF'
## Summary
- Merged topicA: description
- Merged topicB: description
- Merged topicC: description

## Topic PRs
- #N topicA
- #N topicB
- #N topicC
EOF
)"

Step 7: Cleanup

After the root PR is merged:

bash

# Remove worktrees
for wt in worktrees/*/; do
  git worktree remove "$wt"
done

# Delete local and remote topic branches
git branch -d <project-name>/topicA <project-name>/topicB <project-name>/topicC
git push origin --delete <project-name>/topicA <project-name>/topicB <project-name>/topicC

# Delete base branch
git branch -d base/<project-name>
git push origin --delete base/<project-name>

Child Session Workflow

Step 1: Verify Branch

bash

git branch --show-current
# Should show: <project-name>/<topic-name>

Step 2: Implement

Work normally — edit files, run tests, commit.

Step 3: Push and Create PR

bash

git push -u origin <project-name>/<topic-name>

# Create PR targeting the base branch
gh pr create --base base/<project-name> \
  --title "Topic: description" \
  --body "Description of changes"

Branch Naming Conventions

Type	Pattern	Example
Base branch	`base/<project>`	`base/marker-fix`
Topic branch	`<project>/<topic>`	`marker-fix/bogaudio-knobs`
Worktree dir	`worktrees/<topic>`	`worktrees/bogaudio-knobs`

Important Rules

•Always pull main before creating the base branch — stale bases cause conflicts
•Never force push — regular merge only, preserves history
•Topic PRs target the base branch, not main
•Root PR targets main from the base branch
•worktrees/ must be in .gitignore — worktrees are local only
•Manager session stays at repo root — never cd into worktrees for git ops
•Each child session stays in its worktree — git ops affect that branch only

Prerequisites

•worktrees/ in .gitignore
•gh CLI authenticated
•git version 2.15+ (worktree support)

Quick Reference

bash

# Manager: full setup
git checkout main && git pull origin main
git checkout -b base/my-project && git push -u origin base/my-project && git checkout main
git worktree add worktrees/topic1 -b my-project/topic1 base/my-project
git worktree add worktrees/topic2 -b my-project/topic2 base/my-project

# Child: push and PR
git push -u origin my-project/topic1
gh pr create --base base/my-project --title "Topic1: description"

# Manager: merge topics and create root PR
gh pr merge <topic1-pr> && gh pr merge <topic2-pr>
gh pr create --base main --head base/my-project --title "My Project: root PR"

# Manager: cleanup after root PR merged
git worktree remove worktrees/topic1 && git worktree remove worktrees/topic2