This feels like magic, that I can now run multiple agents in parallel and not worry about them stepping on each other.

Forget the merge conflicts and blocked features nightmares; you no longer have to wait for one branch to stabilize before starting another.

I tested this as soon as it was released, and I want to walk you through how it works and how you can set it up today.

If you are not a paid Medium member, you can read the article here for FREE, but consider joining Medium to support my work — Thank you!

But first, you need to understand the problem Claude Code's native Git worktree solves.

Problem With Running One Agent at a Time

Before worktrees, if you were building multiple features simultaneously, you had two options.

• The first was to dump everything into one prompt. "Add dark mode, set up local storage persistence, and add inline editing." Claude would start working, and if one of those three things had a bug, your entire branch was blocked.
• The second option was to manually manage separate branches; create the branch, switch context, start a new session, lose your flow, repeat. This is not the smooth parallel workflow you expect for an agentic workflow.

If you have experienced this problem, you understand that it gets worse the bigger your project gets.

Another concern is in the real-world project management; features don't wait for each other.

Example: The common scenario is you're debugging one thing while building another, and reviewing a third. Your agent shouldn't have to work in a single-file or single-branch lane.

That's the problem, Claude Code native Git worktree fixes.

What Is a Git Worktree?

Before we get into the Claude Code side of things, let me give you a quick basics for what a worktree is — because the name is often misleading.

A git worktree is not a separate repository. It's a separate working directory that's linked to the same repo. Each worktree has its own branch checked out, its own HEAD, and its own working files — but they all share the same git history and objects.

A simpler example:

• Your main project folder is your desk in the office
• A worktree is a second desk in the same office

Both desks have their own papers and tools, but they're pulling from the same filing cabinet.

For Claude Code, it means each agent gets its own isolated environment to work in.

• One agent is building your authentication feature on feature/auth
• Another is fixing a bug on fix/payment-bug

They're not touching the same files, and not waiting on each other.

The key things to know before you start:

• Your project must have git initialized (git init)
• You need at least one commit on the main branch before worktrees will work
• Each worktree checks out a unique branch — two worktrees can't share the same branch at the same time
• When you're done, you can keep the worktree or remove it.

That's the basic Git worktree core concept, but in Claude Code, it is wrapped into a single flag so you don't have to manage it manually. You can learn more about Git worktrees from official docs here.

Getting Started: Claude --worktree Flag

Claude Code v2.1.50 introduced native worktree support with a single flag. Here's how to use it.

Before any of this work, make sure:

• Your project has git initialized (git init) — Let's check if our repo is initialized, use this :

git log --oneline

You have at least one commit on the main branch

• You are on Claude Code v2.1.50 or later (run claude update to check)

We have 2.1.56 (Claude Code)

Starting a Worktree Session

To launch Claude Code in its own worktree, add the --worktree flag (or -w for short):

claude --worktree

This spins up a new worktree with a random branch name chosen by Claude. It works, but if you're running multiple worktrees at once, random names get confusing fast.

Claude Code came up with this name: dreamy-puzzling-codd, and you can see it creates the worktrees directory

The better approach is to name your worktree:

claude --worktree feature/dark-mode

This creates a new worktree checked out on a branch called feature/dark-mode and launches a Claude session inside it — all in one command.

Where Your Worktree Lives

Claude stores worktrees inside your project under:

.claude/worktrees/feature-dark-mode/

You'll find the full set of working files scoped to that branch sitting there. Your main branch is untouched.

To confirm what worktrees are currently active, run:

git worktree list

You'll see your main worktree and each linked worktree listed with their paths and branch names.

Navigating Into a Worktree Directory

If you want to work directly from the worktree's directory instead of the project root, you have two options.

Navigate manually:

cd .claude/worktrees/feature-dark-mode

Or use the --dir flag when launching, which takes you straight there:

claude --worktree feature/dark-mode --dir

Resuming a Worktree Session

One thing I really like — if you close a session and come back later, you can resume where you left off by specifying the same name:

claude --worktree feature/dark-mode

Claude picks up the session for that worktree.

You can also press Ctrl+W inside Claude Code to see all sessions across your project and jump between them.

Cleaning Up When You're Done

Once a feature is merged or you no longer need the worktree, remove it :

git worktree remove .claude/worktrees/feature-dark-mode

Or if the worktree has untracked changes and you want to force remove it:

git worktree remove --force .claude/worktrees/feature-dark-mode

Keep in mind — if you create a lot of temporary worktrees and don't clean them up, they'll pile up under .claude/worktrees/. Make it a habit to prune after merging.

git worktree prune

Running Subagents in Parallel Git Worktrees

Worktrees don't just work for single Claude sessions; subagents support them too.

Instead of one agent juggling multiple features in the same branch, you can have dedicated subagents working on separate branches simultaneously, each in its own isolated worktree.

Triggering Parallel Subagents

From your main Claude session, you can instruct Claude to spin up subagents with worktree isolation like this:

Use worktrees for your agents. Build feature/dark-mode, 
feature/local-storage, and feature/edit-todos in parallel — 
each in its own branch. Make sure each agent tests its changes 
end to end before opening a PR.

Claude will spin up three subagents, each in its own worktree, each on its own branch, all running at the same time.

When one finishes, you can merge or review it independently without waiting for the others.

This is the workflow that previously required manual branch management and multiple terminal sessions.

Configuring Custom Agents with Worktree Isolation

If you have custom subagents defined in your project, you can make worktree isolation automatic by adding isolation: worktree to the agent's frontmatter.

Create or edit your agent file at .claude/agents/your-agent.md:

---
name: feature-builder
model: claude-sonnet-4-6
isolation: worktree
---

You are a feature development specialist. When assigned a feature,
build it completely, write tests, and verify it works before finishing.
Always work in small, focused commits.

With isolation: worktree set, every time this agent is invoked, it automatically gets its own worktree — no flags needed, no manual setup. Claude handles it.

Viewing All Active Sessions

When you have multiple worktrees running, press Ctrl+W inside any Claude Code session to see every active session across the project.

This gives you a quick overview of what each agent is working on and lets you jump between them.

Using the Desktop App

If you prefer not to use the terminal, the Claude Desktop app also supports worktree mode.

Head to the Code tab, and you'll see a worktree checkbox you can enable before starting a session.

It's the same feature, just with a GUI — useful if you're context-switching between the terminal and the desktop app.

Worktrees for Non-Git Projects

If your project uses SVN or Mercurial, you can still get worktree-style isolation through hooks defined in .claude/settings.json:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": "jj workspace add \"$(cat /dev/stdin | jq -r '.name')\""
      }
    ],
    "WorktreeRemove": [
      {
        "command": "jj workspace forget \"$(cat /dev/stdin | jq -r '.worktree_path')\""
      }
    ]
  }
}

This tells Claude to run your version control's workspace commands whenever a worktree is created or removed.

Final Thoughts

Claude Code's native Git Worktrees is an impressive feature for the right use cases.

• Large codebase migrations — Boris Cherny (Claude Code's creator) mentioned using hundreds of parallel agents for large-scale sync-to-async migrations, with each agent handling a folder and opening its own PR.
• Independent features — When your tasks don't share files or depend on each other, parallel worktrees remove all the waiting.
• Bug fixes alongside active development — Fix a production bug in one worktree while continuing to build in another, without any branch contamination.
• Code reviews — Spin up a worktree to review a PR without disturbing your current working branch.

If you're building anything with more than one active feature at a time, this is worth adding to your workflow today.

Have you tried Claude Code Git worktrees and what was your experience?

Claude Code Masterclass Course

Every day, I'm working hard to build the ultimate Claude Code course, which demonstrates how to create workflows that coordinate multiple agents for complex development tasks. It's due for release soon.

It will take what you have learned from this article to the next level of complete automation.

New features are added to Claude Code daily, and keeping up is tough.

The course explores Agents, Hooks, advanced workflows, and productivity techniques that many developers may not be aware of.

Once you join, you'll receive all the updates as new features are rolled out.

This course will cover:

• Advanced subagent patterns and workflows
• Production-ready hook configurations
• MCP server integrations for external tools
• Team collaboration strategies
• Enterprise deployment patterns
• Real-world case studies from my consulting work

If you're interested in getting notified when the Claude Code course launches, click here to join the early access list →

( Currently, I have 11,000+ already signed-up developers)

I'll share exclusive previews, early access pricing, and bonus materials with people on the list.

Let's Connect!

If you are new to my content, my name is Joe Njenga

Join thousands of other software engineers, AI engineers, and solopreneurs who read my content daily on Medium and on YouTube where I review the latest AI engineering tools and trends. If you are more curious about my projects and want to receive detailed guides and tutorials, join thousands of other AI enthusiasts in my weekly AI Software engineer newsletter

If you would like to connect directly, you can reach out here:

Follow me on Medium | YouTube Channel | X | LinkedIn