Git worktrees for Claude Code and Cursor on a Mac

A git worktree is a second (or tenth) checkout of the same repository in its own folder, usually on its own branch. You get isolation for parallel AI coding agents without cloning the repo ten times or fighting over one working tree.

By the end you'll know:

1. What a git worktree actually is
2. How to create one in under a minute
3. How to run multiple AI coding agents on different features at once
4. The easiest way to do all of this with Zoku

The problem (why clones suck)

You want Agent A on auth, Agent B on billing, Agent C on settings.

If they all work in the same folder:

• They overwrite each other's files
• Git gets confused about which branch you're on
• One bad edit nukes another agent's progress

People usually “solve” this by cloning the repo 10 times. That works… until you're juggling 10 copies of node_modules, 10 forgotten branches, and zero shared git history.

Worktrees fix this.

What is a git worktree?

A worktree is a second (or tenth) checkout of the same repo, living in its own folder, usually on its own branch.

You get isolation for agents without pretending you have 10 different repos.

my-project/                 ← main (branch: main)
.zoku/worktrees/
  feature-auth/             ← worktree
  feature-billing/          ← worktree
  feature-settings/         ← worktree

Each folder is a real project directory. Open it in Cursor / Claude Code / Codex. Commit normally. Agents don't step on each other.

Create your first worktree (60 seconds)

From your main repo:

# New branch + folder in one shot
git worktree add ../my-project-auth -b feature/auth

# Or attach an existing branch
git worktree add ../my-project-billing feature/billing

Check what you have:

git worktree list

Remove one when you're done:

git worktree remove ../my-project-auth

That's the whole primitive. Everything else is workflow.

The parallel-agent workflow

This is the pattern that scales past two agents:

1. One worktree per feature — feature/auth, feature/billing, …
2. One agent per worktree — Cursor in one folder, Claude in another, Codex in a third
3. Merge when ready — review PRs independently, land them one at a time

Mental model

Agent 1 → worktree A → branch A → PR A
Agent 2 → worktree B → branch B → PR B
Agent 3 → worktree C → branch C → PR C

Same repo. Same history. Zero interference.

Tips that save you pain

• Name folders after the feature, not the agent (auth-fix, not cursor-3)
• Don't reuse a dirty worktree for a new task — create a fresh one
• Closing a terminal ≠ deleting the worktree — clean up with git worktree remove when the branch is merged
• One agent owns one worktree — never point two write-happy agents at the same folder

By hand vs with Zoku

By hand

Works fine for 2–3 agents:

git worktree add ~/.zoku/worktrees/auth -b feature/auth
git worktree add ~/.zoku/worktrees/billing -b feature/billing
# open each folder in your editor / agent CLI

At 10 agents, the bookkeeping gets annoying: paths, branches, which tile is which, cleanup.

With Zoku

Zoku is a native Mac canvas: one tile per agent, one worktree per tile. Hold ⌥⌘ and say “open a Claude worktree named auth-fix”.

Zoku will:

• Create (or reuse) a worktree for that feature
• Put the agent in its own tile
• Keep agents isolated so they don't overwrite each other

Closing a tile does not delete the worktree — your work stays until you clean it up with git.

That's how you actually run 10 agents on 10 features without turning your machine into a folder graveyard.

Quick start with Zoku

1. Get Zoku for Mac
2. Hold ⌥⌘ and say “open a Claude worktree named auth-fix”
3. Spawn more agents — one feature per tile, one worktree per tile
4. Let them cook in parallel
5. Review → PR → merge → remove stale worktrees when you're done

Cheat sheet

# Create
git worktree add <path> -b <new-branch>
git worktree add <path> <existing-branch>

# List
git worktree list

# Remove
git worktree remove <path>

# After deleting folders by hand
git worktree prune

TL;DR

• Worktrees = multiple folders, one repo, isolated branches
• One worktree per feature = safe parallel agents
• Zoku = the canvas that makes spawning those agents dead simple

Related

• Run multiple Claude Code agents on Mac
• Zoku vs Conductor — a Mac alternative for parallel agents