1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

title: "Five Game-Changing Worktree Tricks in Claude Code to Transform Your Workflow"
date: 2026-03-11T23:30:00+01:00
draft: false
slug: "claude-code-worktrees-parallel-agents-tips"
slug_en: "claude-code-worktrees-parallel-agents-tips"
description: "Claude Code has native support for git worktrees: --worktree, isolated sub-agents, custom agents with isolation, --tmux for parallel sessions. Five tips from Boris Cherny."
tags: ["claude-code", "git", "worktrees", "productivity", "workflow", "agents"]
categories: ["tools"]

translation:
  hash: ""
  last_translated: ""
  notes: |
    - "mola": colloquial for "it's cool" / "it's great". Very common in Spain.
    - "irse de cañas": "going out for beers". Spanish social ritual, casual.
    - "ñapa": "quick hack/bodge". Not derogatory, somewhat affectionate.
    - "dicho en cristiano": "in plain language". No religious connotation.
    - "barra del bar": "bar counter" — casual conversation metaphor.
    - "te comes un conflicto": "you'll get a conflict" — eating metaphor, common in Spain.
    - "currar": colloquial for "to work". Very common in Spain.

social:
  publish: true
  scheduled_date: 2026-03-14
  platforms: ["twitter", "linkedin"]
  excerpt: "Claude Code has native support for git worktrees. It's not just 'git worktree add.' It's --worktree, isolated sub-agents, custom agents with isolation: worktree, and --tmux for parallel sessions. Five tricks to transform your workflow."

wordpress:
  publish: true
  categories: [1]
  tags: ["claude-code", "git", "worktrees", "productivity", "workflow"]

video:
  generate: false
  style: "educational"
---

A few weeks ago, I wrote about [git worktrees](/posts/git-worktrees-coding-agents-parallel/) — what they are, how to create them, and why they’re better than cloning a repo three times. The basics.

But the basics are only half the story. Because Claude Code doesn’t just work *with* worktrees — it has native support for them. Dedicated flags, automatic isolation, integration with tmux. And the difference between knowing worktrees exist and knowing how Claude Code uses them is like the difference between having a car and knowing it has sport mode.

Boris Cherny, the creator of Claude Code, shared a thread with five tips on how to make the most of them. I’ve tried them all. Some have totally transformed how I work. Others spared me the quick hacks I’ve been cobbling together since January. Let’s dive in.

## Tip 1: `--worktree` — Create a worktree with one flag

The classic flow for working with a worktree looks like this:

```bash
git worktree add ../my-project-feature -b feature/something
cd ../my-project-feature
claude

Three steps. Not terrible, but you have to think up directory names, remember the syntax, and navigate to the new directory. If you do this five times a day, it gets old.

Claude Code simplifies this to one step:

1

claude --worktree

That’s it. Claude creates a temporary worktree in a generated directory, moves into it, and starts a session there. When you’re done, the worktree cleans itself up.

When do I use this? Every time I want to experiment without contaminating my current branch. Testing out an aggressive refactor, exploring an alternative design, doing a spike. If it works, I merge. If it doesn’t, it vanishes without a trace.

It’s the equivalent of opening a new draft in your text editor. No commitment, no ceremony.

Tip 2: Sub-agents in isolated worktrees

If you already use sub-agents in Claude Code (via Task inside a custom agent or via task delegation from the main agent), you know they share the working directory. That means two sub-agents can overwrite each other’s files, compete for git’s index, or turn the staging area into a complete mess.

The solution: sub-agents running in their own isolated worktrees.

When an agent launches a sub-agent with worktree isolation, Claude Code:

1. Creates a temporary worktree for the sub-agent.
2. The sub-agent works there, on its own branch.
3. When it finishes, changes can be merged back to the parent worktree.
4. The temporary worktree is cleaned up.

In plain language: every sub-agent gets its own workspace. They can both saw wood at the same time without sawing each other’s fingers off.

The benefit isn’t just avoiding conflicts. It’s that you can truly parallelize. Let one sub-agent write tests while another implements a feature. One translates documentation while another refactors the authentication module. No waiting, no blocking.

Tip 3: Custom agents with isolation: worktree

This is where things get really interesting. Custom agents in Claude Code are defined with a Markdown file in .claude/agents/. And in the frontmatter of that file, you can add:

1
2
3
4

---
name: refactor-module
isolation: worktree
---

isolation: worktree tells Claude Code: “Every time you run this agent, give it its own worktree automatically.” You don’t need to pass --worktree. You don’t need to create anything manually. Isolation is built right into the agent’s definition.

When is this useful? For agents that, by design, should always work in isolation. Examples:

An aggressive refactoring agent. You want an agent to move files, rename functions, restructure directories. If you do this in your working branch, any mistake becomes a disaster. With isolation: worktree, the agent makes changes in its own copy. You review the diff. If you’re happy, you merge. If not, git worktree remove and it’s like it never happened.

A translation agent. I literally use this for this blog. An agent that translates posts into four languages, generates frontmatter, and commits. It needs to touch many files at once. If it works in my development directory, it blocks me. In its own worktree, it translates while I keep writing the next post.

A database migration agent. It generates SQL files, validates them against the current schema, and runs tests. All in an isolated worktree where it can break things without consequences.

The key is that isolation: worktree makes isolation a property of the agent, not a decision you make every time you run it. It’s the difference between a car having airbags and a car where you have to remember to activate safety features every time you start it.

Tip 4: --tmux — Truly parallel sessions

Up until now, “parallel” meant manually opening multiple terminals. Terminal 1 for one worktree, Terminal 2 for another, Terminal 3 for the main branch. It works, but it’s clunky.

--tmux automates this:

1

claude --worktree --tmux

Claude Code creates the worktree, starts the session in a tmux panel, and gives you back control of your terminal. You can launch three, four, five sessions like this:

1
2
3

claude --worktree --tmux  # session 1: implement feature A
claude --worktree --tmux  # session 2: write tests for module B
claude --worktree --tmux  # session 3: refactor the CLI

Each in its own worktree, each in its own tmux panel, all running in parallel. Switch between them with Ctrl-b + window number (or your favorite tmux shortcut).

This is a game changer for productivity sprints. Picture a Monday morning: you open your backlog, pick three independent tasks, and launch three agents. While one writes tests, another implements a feature, and the third updates documentation. You supervise, review diffs as they finish, and merge.

This isn’t science fiction. It’s a flag.

Tip 5: When NOT to use worktrees

As important as knowing when to use worktrees is knowing when not to. Boris Cherny says this explicitly, and I agree.

Don’t use worktrees for sequential tasks. If Task B depends on the result of Task A, there’s no benefit to parallelizing. In fact, you lose: now you have to merge Task A before Task B can start, adding a step that wouldn’t exist if you just worked on the same branch.

Don’t use worktrees for small changes. A one-line fix doesn’t justify the ceremony of creating a worktree — even if --worktree reduces it to one flag. The mental overhead of juggling multiple active directories isn’t worth it for a 30-second change.

Don’t use worktrees if changes touch the same files. If Feature A and Feature B are both going to modify config.toml or routes.py, you’re guaranteed a merge conflict. Worktrees shine when features are orthogonal — touching different parts of the code.

Don’t use worktrees without a plan. Launching five agents in parallel “just to see what happens” sounds productive. In reality, you end up with five branches of unknown state, five diffs to review, and five potentially conflicting merges. Parallelization works when there’s intention behind it: clear, independent tasks with defined acceptance criteria.

The golden rule: if you can describe each task in one sentence and none depend on each other, use worktrees. If not, work serially.

The complete workflow: From theory to your Monday morning

To keep it concrete, here’s the flow I use now for tackling multiple independent tasks in the backlog:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# 1. Review backlog and pick independent tasks
linear issue list --team PROD --state unstarted --sort priority --no-pager

# 2. Launch one agent per task, each in its own worktree + tmux
claude --worktree --tmux  # "implement feature X, write tests"
claude --worktree --tmux  # "refactor module Y"
claude --worktree --tmux  # "translate pending posts"

# 3. Review progress as they finish (tmux panels)
# Ctrl-b + 1, 2, 3 to switch between sessions

# 4. Review the diff of each worktree
cd /tmp/claude-worktree-abc123  # or wherever Claude created it
git diff main

# 5. If the diff looks good, push + PR
git push -u origin feature/whatever
# PR, review, merge

# 6. Cleanup (or let Claude do it automatically)
git worktree list  # see what’s still active

What used to take me an entire morning — three features developed, tested, and PR-ed — can now be done before heading out for beers.

The evolution: From manual to native

When I first started using worktrees a few weeks ago, everything was manual. git worktree add, cd, claude, open another terminal, repeat. It worked, but it felt like pitching a tent every time you wanted to step outside.

With --worktree, isolation: worktree, and --tmux, Claude Code has made worktrees disappear. You don’t think about them. You don’t manage them. You just say “work in parallel,” and the tooling takes care of the rest.

It’s the same evolution we saw with containers: first you configured LXC by hand, then Docker abstracted it, and now you don’t even think about kernel namespaces. Worktrees are at that stage of abstraction. Git laid the foundation in 2015. Eleven years later, the tooling is finally making them invisible.

And that’s what we want from any tool in the end: to do its job and get out of the way.

TL;DR: Claude Code has five key worktree features: --worktree (create and start in one flag), isolated sub-agents (each in its own worktree), isolation: worktree for custom agents (isolation by design), --tmux (automated parallel sessions), and knowing when not to use them. The result: true parallelism without manual management. Worktrees go from a git feature nobody uses to the invisible infrastructure of your workflow with agents.