Cursor worktrees vs Claude Code worktrees: four differences that matter

Last updated: November 8, 2026

TL;DR

Cursor worktrees and Claude Code worktrees do the same job, giving each agent its own git checkout so parallel edits don't collide. They differ in four places: how you start one, how the new checkout gets set up, how changes come back to your main checkout, and how old worktrees get cleaned up. Each also covers one parallel pattern the other's docs don't.

• 🚀 Starting one. Cursor starts worktrees from its Agents Window, or with /worktree in the IDE. Claude Code starts them with claude -w <name> or when you ask Claude to.
• 🧰 Setting it up. Cursor runs your setup commands from .cursor/worktrees.json. Claude Code copies the gitignored files you list in .worktreeinclude, and you install dependencies.
• 🔁 Bringing changes back. Cursor has /apply-worktree to pull a result into your main checkout. In Claude Code, the worktree is a branch you commit, push or merge like any other.
• 🧹 Cleaning up. Cursor keeps the newest worktrees up to a machine-wide count, 25 by default. Claude Code decides per worktree, from whether it holds work.
• 🧪 One extra pattern each. Cursor's /best-of-n runs one task on several models. Claude Code can pin a subagent to its own worktree.
• 🧭 Which fits. Editor-first work leans Cursor, terminal-first and scripted work leans Claude Code.

Side by side, since both tools use git worktrees under the hood and differ in the workflow around them:

The Cursor column comes from Cursor's worktrees docs, the Claude Code column from Anthropic's worktrees guide, both read November 7, 2026.

Starting a worktree: a window in Cursor, a flag in Claude Code

Cursor starts worktrees from its Agents Window and Claude Code starts them from the command line, so the choice follows where you already work.

Cursor. The UI-native feature lives only in the Agents Window, where you start an agent in a worktree or move one into it. In the IDE, you start a task with the /worktree command, and Cursor does the rest of that chat in a separate checkout:

/worktree fix the failing auth tests and update the login copy

Claude Code. Pass -w with a name, and Claude Code creates the worktree under .claude/worktrees/<name>/ on a new branch called worktree-<name>:

claude -w feature-auth

You can also ask Claude to "work in a worktree" partway through a session. Our guide to Claude Code worktrees covers branching from a pull request, reusing names and the errors you can hit.

Setting up the checkout: scripts in Cursor, a file list in Claude Code

Cursor runs setup commands in each new worktree, while Claude Code only copies files and leaves the rest to you or to Claude.

Cursor reads .cursor/worktrees.json when it creates a worktree, from the Agents Window, the IDE or the Cursor CLI. It looks in the worktree first, then in your project root. The file takes an array of shell commands or a path to a script, with separate keys for macOS and Linux, Windows, and a generic fallback:

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

$ROOT_WORKTREE_PATH points at your main checkout, which is how the .env gets copied. Cursor recommends against symlinking dependencies into a worktree, since that can cause problems in the main one, and suggests a fast package manager such as bun, pnpm or uv instead. To debug setup, open the Output panel and select Worktrees Setup.

Claude Code copies gitignored files listed in a .worktreeinclude file at your project root, written in .gitignore syntax:

.env
.env.local

It runs no install step of its own. A worktree is a fresh checkout, so you install dependencies there yourself or ask Claude to. For anything more, a WorktreeCreate hook replaces Claude Code's git logic entirely, and then the hook copies the files itself.

Bringing changes back: an apply command in Cursor, a branch in Claude Code

Cursor gives you a command to pull a worktree's result into your main checkout, and Claude Code treats the worktree as an ordinary branch.

Cursor. After an agent finishes in the Agents Window, you review the result and can keep working in the worktree, commit or open a PR from it, or bring the result back into your main workspace. In the IDE, /apply-worktree brings the changes into your main checkout to test them, and /delete-worktree removes the isolated checkout when you're done. You can also ask the agent to commit, push and open a PR straight from the worktree.

Claude Code. Each worktree sits on its own branch, so you commit, push and open a pull request from it, or merge it, with your normal git workflow. When you exit, Claude Code checks the worktree for uncommitted changes, untracked files and new commits before it offers to remove anything.

Cleaning up: Cursor counts, Claude Code checks for work

Cursor cleans up by keeping the newest worktrees up to a count, while Claude Code decides worktree by worktree based on whether it holds work.

Cursor, from version 3.5, runs cleanup on an interval and keeps the newest worktrees up to a machine-wide maximum across every workspace. Two settings control it:

{
  "cursor.worktreeCleanupIntervalHours": 6,
  "cursor.worktreeMaxCount": 25
}

The default cap is 25 worktrees per machine, and every workspace counts toward it. Cursor re-discovers its worktree root on each pass, so worktrees created outside its manager, such as ones from the /worktree command or git worktree add, are eligible for deletion too. When creating a worktree would pass the cap, Cursor starts a cleanup right away.

Claude Code checks each worktree when you exit an interactive session. A clean worktree from an unnamed session is removed with its branch, and a worktree with changes, untracked files or new commits prompts you to keep or remove it. Worktrees created for subagents and background sessions go in a periodic sweep once they're older than your cleanupPeriodDays setting, and the sweep skips any that still hold work. Worktrees from non-interactive -p runs stay until you remove them with git worktree remove.

Either way, commit or push anything you want to keep before cleanup gets to it.

Comparing models and isolating subagents

Each tool covers one parallel pattern the other's worktree docs don't.

Cursor's /best-of-n runs the same task across several models at once, each in its own worktree:

/best-of-n sonnet,gpt,composer fix the flaky logout test

It compares the runs and doesn't merge anything. You pick a winner, then commit from its worktree or use /apply-worktree.

Claude Code's subagent isolation gives each subagent its own temporary worktree. Ask Claude to "use worktrees for your agents", or add isolation: worktree to a custom subagent's frontmatter. A subagent worktree with no changes is removed when the subagent finishes. When to reach for subagents rather than agent view or agent teams is in our guide to how to run Claude Code agents in parallel.

Cursor worktrees or Claude Code worktrees: which fits how you work

Pick by where you already spend the day, then by how much setup each worktree needs:

If you run both, keep one set of project rules for them. Our guide to AGENTS.md vs CLAUDE.md covers which file each agent reads and how to share one.

Frequently asked questions

What is a Cursor worktree?

A Cursor worktree is a separate git checkout that a Cursor agent works in, with its own files, dependencies and changes, while your main checkout stays untouched. You start one from the Agents Window or with /worktree in the IDE, and Cursor runs any setup in .cursor/worktrees.json.

What is the difference between Cursor worktrees and Claude Code worktrees?

Both give each agent its own git checkout. Cursor starts them from its Agents Window or /worktree, runs setup scripts, brings results back with /apply-worktree and cleans up by count. Claude Code starts them with claude -w, copies listed files and cleans up based on whether each worktree holds work.

How many worktrees does Cursor keep?

Cursor keeps up to 25 worktrees per machine by default, counted across every workspace, and cleans up older ones on an interval, every 6 hours by default. Change the limits with the cursor.worktreeMaxCount and cursor.worktreeCleanupIntervalHours settings.

Where does Claude Code put worktrees?

Under .claude/worktrees/<name>/ at your repository root, on a branch named worktree-<name>. Add .claude/worktrees/ to your .gitignore so the contents don't show up as untracked files.

How do I copy my .env file into a worktree?

In Cursor, add a command such as cp $ROOT_WORKTREE_PATH/.env .env to setup-worktree in .cursor/worktrees.json. In Claude Code, list .env in a .worktreeinclude file at the project root, and Claude Code copies it into every worktree it creates with git.

How do I bring changes from a worktree back to my main branch?

In Cursor, run /apply-worktree to bring the changes into your main checkout, or commit and open a PR from the worktree. In Claude Code, the worktree is its own branch, so commit and push it, open a pull request, or merge it with git.

Can I compare several models in worktrees?

In Cursor, yes: /best-of-n runs one task across several models, each in its own worktree, and leaves the choice to you. Anthropic's worktrees guide doesn't describe a multi-model comparison for Claude Code.

Keep the rules where every worktree reads them

Every new worktree, in either tool, starts with your repository's files and none of the context in your head. The rules you keep in the repo are what each parallel agent inherits. Our guide to compound engineering for Claude Code shows how to build those rules up one fix at a time.