Claude Code Worktrees: Parallel Work Explained

What are worktrees in Claude Code?

Worktrees are one of Claude Code's most underused features. They let you spin up an isolated copy of your repository in a separate git branch, run a task there, and merge the results back, all without touching your working directory.

Think of it as parallel execution with git-level isolation. Your main branch stays clean while Claude works on something in a temporary branch.

Why worktrees matter

Without worktrees, every task Claude runs modifies your working directory directly. If you're mid-feature and ask Claude to do a refactor, the refactor changes mix with your feature changes. Messy commits, hard-to-review PRs, and risk of conflicts.

Worktrees solve this by giving each task its own sandbox:

Main branch: your feature work (untouched)
├── Worktree 1: refactoring task (isolated)
├── Worktree 2: bug fix (isolated)
└── Worktree 3: dependency update (isolated)

Each worktree operates on its own copy of the repo. Changes don't bleed between them.

How to use worktrees

In Claude Code, you can request a worktree for any task:

Run this refactor in a worktree so it doesn't affect my current work

Claude will:

1. Create a new git worktree with a temporary branch
2. Execute the task in that isolated copy
3. Return the results with the branch name
4. You can review and merge when ready

For agents spawned via the Agent tool, you can set isolation: "worktree" to automatically run them in isolation.

When to use worktrees

Use worktrees for:

• Large refactors that touch many files
• Experimental changes you might want to discard
• Tasks that could break your current build
• Running multiple independent tasks in parallel
• Code review or audit tasks (read-only analysis in isolation)

Don't use worktrees for:

• Quick, single-file edits
• Tasks that depend on your current uncommitted changes
• Anything that needs to see your in-progress work

Worktrees + agents

The real power comes from combining worktrees with Claude Code agents. Each agent runs in its own worktree, working on a separate task simultaneously:

Agent 1 (worktree): Refactoring authentication module
Agent 2 (worktree): Writing tests for the API layer
Agent 3 (worktree): Updating documentation

All three run in parallel without conflicting. When they finish, you review each branch independently and merge what you want.

Worktree lifecycle

1. Created: Fresh copy of the repo at the current commit
2. Working: Agent or task runs in isolation
3. Completed: Changes committed to the temporary branch
4. Cleanup: If no changes were made, the worktree is automatically deleted. If changes exist, the branch persists for review.

You're never left with abandoned worktrees cluttering your repo.

Practical patterns

Pattern 1: Safe refactoring

Refactor the database layer to use connection pooling.
Run this in a worktree. I don't want it touching my current branch.

Review the diff. Merge if it looks good. Discard if it doesn't.

Pattern 2: Parallel exploration

When you're not sure which approach is best:

Try three different approaches to the caching problem:
1. Redis-based caching (worktree)
2. In-memory LRU cache (worktree)
3. File-based cache with TTL (worktree)

Compare the implementations and recommend one.

Pattern 3: Automated code review

Run a security audit on the entire codebase in a worktree.
Don't modify any files, just report findings.

The worktree gives the audit a clean snapshot without risk of accidental changes.

Worktrees in a complete system

Worktrees handle isolation. But a complete workflow needs more: persistent memory to track what's in each branch, commands to standardize how you create and manage worktrees, and hooks to enforce safety rules across all worktrees.

Claudify provides the full system: memory that persists across branches, commands that automate common patterns, and agents that know how to work in isolation. One install: npx create-claudify.

Get Claudify: 21 commands, 9 agents, 1,727 skills. Built for real workflows.