The Git Worktree + Claude Code Playbook

Result first: use Git worktrees plus Claude Code to ship two things at once. No stashing. No tab chaos. This playbook shows you how to set it up fast and run it every day.

What you ll build

A simple, repeatable workflow that lets you run two or more Claude Code sessions in the same repo, each with its own branch and folder. You can build a feature and fix a hot bug at the same time without merge mess.

Why Git worktrees + Claude Code

• True parallel work: separate folders for each branch. Claude stays focused per task (official common workflows).
• Less context switching: no git stash dance (worktrees guide).
• Agentic automation: Claude acts like a junior dev, plans steps, edits files, and works with Git and tools (practical guide, best practices).
• Fits your process: tune behavior with CLAUDE.md and custom commands (CLI + MCP tips, complete guide).

Setup checklist (copy and run)

• Git 2.38+ installed.
• Claude Code CLI installed and logged in (docs).
• Repo is clean on main and synced.
• Remote origin set to GitHub or GitLab.
• Optional: Jira/GitHub MCP access for tickets and PRs (MCP examples).
• CLAUDE.md in repo root with branch rules and commit style (CLAUDE.md tips).

Sample CLAUDE.md (start here)

# Team Rules
- Branch naming: feature/*, fix/*, hotfix/*
- Commits: conventional commits (feat, fix, chore, docs, refactor, test)
- PR: link ticket ID, checklist, test plan

# Git/Code Tasks
- When given a ticket: create branch, write plan, implement in small steps, run tests, commit often, open draft PR.
- Use worktrees for parallel tasks.

Quick start: 10-minute setup

1. Create two worktrees one for a feature, one for a bug fix.
2. Run Claude in each folder. Keep sessions separate.
3. Commit and open PRs from each branch.

# From your main repo folder
# 1) Create a feature worktree
git worktree add ../app-feature-auth -b feature/auth-improvements

# 2) Create a bugfix worktree
git worktree add ../app-fix-404 -b fix/404-on-profile

# 3) Start Claude Code in each (two terminals)
cd ../app-feature-auth
claude

cd ../app-fix-404
claude

Claude can handle many Git steps for you. Anthropic engineers use it for most Git actions (best practices).

Depth module: the parallel workflow

1) Plan each task with a tiny brief

• Feature brief: what to add, acceptance tests, risks.
• Fix brief: how to reproduce, expected vs. actual, test path.

# In each Claude session
"Plan the work. Show a step list. Create tests first. Then code in small chunks. Commit with conventional commits."

2) Code in small steps, commit often

Short loops keep you safe and fast. Ask Claude to stage and commit when a small unit passes.

# Example commits Claude can help generate
feat(auth): add password strength check

fix(profile): handle missing user for 404 route

test(api): add coverage for profile 404

3) Run tests and linters inside each worktree

# Typical commands (adjust for your stack)
npm test
pytest -q
go test ./...

# Ask Claude to run and summarize output

4) Open draft PRs early

Let reviewers see progress. Claude can prep a clear PR body and link tickets via MCP (MCP integration).

# From each worktree
git push -u origin feature/auth-improvements
# Open PR (Claude or your tool)

5) Merge safely

• Squash if you want tidy history.
• Keep main always deployable (Microsoft guidance, branch strategy).

ASCII workflow (at a glance)

Main repo (./app)
   |
   +-- worktree A (../app-feature-auth) -> branch: feature/auth-improvements -> Claude session A
   |
   +-- worktree B (../app-fix-404)     -> branch: fix/404-on-profile       -> Claude session B

Push PRs independently. Merge when green.

Daily operating checklist

• Pull main, update worktrees: git fetch --all.
• Keep sessions focused: one goal per worktree.
• Commit in small units. Write tests.
• Open PRs early. Get feedback.
• Remove old worktrees when merged.

# See and clean up worktrees
git worktree list
git worktree remove ../app-feature-auth

Team patterns that work

Onboarding new engineers

• Give them a worktree to explore the code. Let Claude answer questions and map files (onboarding pattern).

Ticket-to-PR flow

• Claude can create a branch, plan changes, and open a draft PR with checklists and ticket links (examples, video workflow).

Automated commits on session end

• Use Claude Code hooks to auto-commit with the last message handy for long runs (hooks post).

# Idea: auto-commit at session end (see blog for full script)
# hooks read transcript, stage changes, commit-tree, and update ref.

Branching strategy: pick what fits

Strategy	Good for	Notes
GitHub/feature branches	Most teams	Simple: branches off main + PRs (overview).
GitFlow	Release-heavy products	More branches. Some say it’s dated for CI/CD (guide, critique, discussion).
Trunk-based	Fast deploy teams	Small, frequent merges to main.

Tip: keep main green and deployable. Use feature flags if you ship often (Microsoft guidance).

Claude-specific pro tips

• Worktrees scale Claude: run one session per task for clean context (docs).
• Use CLAUDE.md as team infra. Commit and review it like code (guide).
• Define slash commands for common flows: plan, commit, test, PR (Git Flow commands).
• Add PR templates and checklists so Claude fills them right (template examples).
• Let Claude run 90% of Git steps; you review and approve (best practices).

Troubleshooting

Worktree won t add

• Make sure the branch doesn’t exist locally.
• Use -b to create it: git worktree add ../path -b feature/x.

Claude edits the wrong folder

• Start Claude inside the target worktree folder.
• Confirm with pwd and git status.

Conflicts on merge

• Pull latest main before opening PR.
• Rebase or merge main into your branch, resolve, re-run tests (merge basics).

Slow sessions

• Reduce task size. Ask Claude to plan smaller steps.
• Close idle sessions. One goal per worktree.

FAQ

Do I still need branches?

Yes. Each worktree maps to a branch. That’s the point: separate tasks, clean history.

Can Claude open PRs and link tickets?

Yes, with the CLI and MCP it can pull ticket data and open draft PRs (MCP).

Is this better than just switching branches?

For parallel work, yes. No stashing. No lost changes. Claude stays focused in each session (docs).

End-to-end example: feature + hotfix

1. Create two worktrees.
2. Start Claude in both.
3. Feature session: write a plan, add tests, code, commit, push PR.
4. Hotfix session: reproduce bug, write failing test, fix, commit, push PR.
5. Merge hotfix first. Then merge feature when green.

# Commands recap
# Feature
git worktree add ../app-feature-auth -b feature/auth-improvements
cd ../app-feature-auth
claude

# Bugfix
git worktree add ../app-fix-404 -b fix/404-on-profile
cd ../app-fix-404
claude

# Push branches
git push -u origin feature/auth-improvements
git push -u origin fix/404-on-profile

Keep it simple

• One task per worktree.
• Short steps. Frequent commits.
• PR early. Merge when tests pass.
• Remove old worktrees. Stay tidy.

Want more patterns and examples? See the automation guide, Anthropic’s best practices, and the official workflows. If you use heavy releases, read Atlassian’s workflow overview and choose what fits your team today.

Next step (5 minutes)

1. Add CLAUDE.md with your branch and commit rules.
2. Create two worktrees for your top tasks.
3. Start Claude in both. Ask it to plan and ship the first small step.

Result: parallel progress and fewer blockers. Ship it.