DEV Community

Cover image for Git Worktrees: The Power Behind Cursor’s Parallel Agents
Ariful Alam
Ariful Alam

Posted on

Git Worktrees: The Power Behind Cursor’s Parallel Agents

#git #ai

Cursor just shipped Parallel Agents, a way to run multiple agents on different tasks at the same time. Under the hood, this relies on Git worktrees so that each agent can safely operate on its own branch and working directory without stepping on the others. If you’re new to worktrees, this guide is for you.

What is a Git worktree?

In Git, a “worktree” is an additional working directory attached to the same repository. Each worktree:

  • Has its own working directory, index, and HEAD pointing at a branch or commit
  • Shares the repository’s object database (no duplicate history)
  • Can be used simultaneously with other worktrees

This means you can open repo/ for main, and repo-feature/ for feature/login, both fully editable, both real directories, both backed by the same .git object store.

Why not just clone twice?

  • Clones duplicate the entire repository data and configuration
  • Worktrees are much faster to create and take far less disk space
  • Worktrees keep remotes, hooks, and config shared, reducing drift

How worktrees are structured (under the hood)

When you add a worktree, Git creates metadata in the primary repo’s .git/worktrees/<name> and a small .git file inside the new working directory that points back to the main repo. Objects and refs live centrally; each worktree has its own HEAD and index state.

Key consequence: operations that depend on repository objects (fetch, gc, hooks, config) are shared; operations that depend on the working directory (add, commit, checkout) are isolated per worktree.

Core commands (cheat sheet) 

# List active worktrees
git worktree list

# Add a new worktree at ./../feature-abc, checking out branch feature/abc
git worktree add ../feature-abc feature/abc

# Create a new branch and worktree in one go
git worktree add ../hotfix-1.2 -b hotfix/1.2

# Add a detached worktree at a specific commit (read-only is typical)
git worktree add --detach ../investigate abc1234

# Prune (remove metadata for missing worktree directories)
git worktree prune

# Remove a worktree safely (directory must be clean or use --force)
git worktree remove ../feature-abc
git worktree remove --force ../feature-abc
Enter fullscreen mode Exit fullscreen mode

Pro tips:

  • Use -b <new-branch> to create a branch when adding the worktree.
  • Keep directory names short and descriptive, e.g. ../feat-reporting or ../bug-2174.

How Cursor Parallel Agents use worktrees

Cursor’s Parallel Agents run multiple agents side-by-side. Each agent operates in an isolated Git worktree and typically on its own branch. This provides:

  • Isolation: File edits and indexes are separate, so agents don’t clobber each other.
  • Speed: Creating worktrees is fast and space-efficient compared to full clones.
  • Traceability: Each agent’s branch records its history and diffs cleanly.

Read the product documentation for configuration details and tips: Cursor Worktrees documentation.

Example: parallel feature + hotfix 

# You’re on main in the primary directory
git pull --ff-only

# Start a feature in its own worktree
git worktree add ../feat-reporting -b feature/reporting

# Meanwhile, a production bug appears; cut a hotfix worktree
git worktree add ../hotfix-2174 -b hotfix/2174 origin/release/1.2

# In ../hotfix-2174, implement the fix, test, and ship
git commit -am "Fix NPE in invoice total"
git push -u origin hotfix/2174

# Back in ../feat-reporting, continue development uninterrupted
Enter fullscreen mode Exit fullscreen mode

Cleanup checklist

  • Merge or push branches you want to keep.
  • git worktree remove <path> for each finished worktree.
  • git worktree prune to clear any stale metadata.
  • Optionally delete remote branches after merging.

When to choose worktrees vs. alternatives

  • Worktrees: Best for fast, space‑efficient, parallel workflows in the same repo.
  • Separate clones: Useful when you need different remotes, radically different config, or to isolate heavyweight tooling state.
  • Stashing / single checkout: Fine for quick context switches, but becomes fragile for serious parallelism.

If you’re trying out Cursor’s Parallel Agents, learning Git worktrees will pay immediate dividends. They’re simple, fast, and map perfectly to how you want to parallelize real‑world work.

Top comments (0)