Git Worktrees Are the Missing Primitive

When you run three AI coding agents simultaneously on the same repository, you have a concurrency problem. Each agent thinks it owns the branch. Each makes changes. Conflicts happen. Context gets mixed.

Git worktrees solve this — but almost nobody uses them with AI agents.

What’s a Git Worktree?

A git worktree is a separate working directory linked to the same git repository. Each worktree can be on a different branch, with its own index and HEAD.

git worktree add ../feature-auth feature/auth
git worktree add ../fix-payments fix/payments

Now you have two independent working directories, each on their own branch, sharing the same git history. No stashing. No branch switching. True parallelism.

Why AI Agents Need Worktrees

An AI coding agent working on feature/auth should never see the uncommitted changes from your fix/payments work. Without worktrees, your agents share a working directory — which means:

  • Uncommitted changes from one task confuse another agent
  • Agents can accidentally stage each other’s work
  • Context bleeds between unrelated tasks

With worktrees, each agent gets its own clean slice of the repository. They work in parallel without interference.

How Nexus Implements This

Nexus Prime’s worktree manager does three things:

  1. Creates isolated worktrees per agent session
  2. Scopes memory to each worktree namespace
  3. Cleans up after sessions end, leaving git history clean
nexus-prime worktree create feature/auth --agent cursor
# Cursor now works in an isolated worktree
# Memory is scoped to feature/auth namespace

The dashboard at localhost:3377 shows all active worktrees, which agent owns each, and their current status.

The Right Mental Model

Think of worktrees as “agent lanes” — each agent gets its own lane on the same highway. They move in parallel, share the same destination (your git history), but never collide.

Free tier: 3 concurrent worktrees. Pro Solo: unlimited.