Skip to main content
Git worktrees started as a way to handle emergency hotfixes without stashing your work. Now they’re how developers run multiple AI coding agents at the same time. If you’re using Claude Code, Cursor, or Opencode, you’ve probably hit a wall trying to run two agents in the same directory. Worktrees fix that problem, but they come with their own set of headaches. The idea is simple: each AI agent works better when it has its own isolated workspace. Worktrees give you that isolation without cloning your entire repository five times.

​
How worktrees actually work

A git worktree is a linked working directory that shares the same .git data as your main checkout. When you run git worktree add ../feature-branch feature-branch, Git creates a new directory with its own files. It reuses the object database, refs, and configuration from your original repository. Here’s what happens under the hood. Each linked worktree contains a .git file (not a folder) with one line pointing back to the main repo: gitdir: /path/main/.git/worktrees/feature-branch. Git sets $GIT_DIR for worktree-specific data like HEAD and the staging area. It uses $GIT_COMMON_DIR for shared resources. Why not clone five times? A clone duplicates the entire Git object database. With a 500MB repository, five clones eat up 2.5GB. Five worktrees only duplicate working files while sharing history. One git fetch updates all worktrees at once. Commits you make in any worktree show up in all the others. Here are the commands you’ll use: 
# Create worktree with new branch
git worktree add -b feature-auth ../auth-work main

# List all worktrees
git worktree list

# Remove when done
git worktree remove ../auth-work

# Clean up stale references
git worktree prune
Before AI agents came along, developers used worktrees for context switching. You could handle an emergency hotfix without stashing messy work-in-progress. You could review pull requests without losing your place. You could run git bisect without destroying your working state.

​
Why AI agents need worktrees

AI coding assistants created a new use case: running multiple agents at once. Anthropic’s Claude Code documentation recommends worktrees for multi-session workflows. They let you run “multiple Claude sessions simultaneously on different parts of your project, each focused on its own independent task.” Cursor built their “Parallel Agents” feature directly on worktrees. Here’s why developers keep using this setup:
  • Context isolation: Each agent sees only its worktree’s files. No confusion between features.
  • Preserved conversation history: Switching branches in one directory confuses an agent’s context. Worktrees keep things separate.
  • Safe experimentation: Let an agent try a risky refactor in an isolated worktree. If it fails, delete the worktree.
  • Run the same prompt twice: Give the same task to different agents. Pick whichever result you like better.
Nick Mitchinson puts it well: “When an AI agent is working on one feature, you don’t want it accidentally referencing or modifying files from another feature branch. Worktrees provide complete isolation.”

​
Where worktrees fall apart

Running multiple worktrees sounds great until you try it. Developer forums and GitHub issues document the same problems over and over. Port conflicts hit you first. Every dev server defaults to the same ports: 3000, 5432, 8080. Launch two React apps from different worktrees and one fails. The workaround looks like this: SERVICE_PORT = BASE_PORT + (WORKTREE_INDEX * 10) + SERVICE_OFFSET. But you need to build scripts that scan for available ports and update .env files per worktree. Dependencies don’t carry over. Your node_modules doesn’t exist in new worktrees. Neither does .env (which is gitignored, as it should be). Each worktree needs npm install or npm ci, eating up time and disk space. That’s where pnpm will help a lot in symlinking packages and downloading them only once. IDE support is inconsistent. JetBrains products have no native worktree creation UI. Command line only. VS Code added worktree support in July 2025. Claude Code’s /ide command fails to recognize worktrees, reporting “No available IDEs detected” because workspace paths don’t match the current directory. GitLens and Tower work better, but the ecosystem is fragmented. Database isolation doesn’t exist. Worktrees share the same local database, Docker daemon, and cache directories. Two agents modifying database state at the same time creates race conditions. You can fix this with per-worktree database instances and worktree-indexed Docker volume names, but that’s a lot of setup. Disk space adds up fast. Cursor forum users reported that in a 20-minute session with a ~2GB codebase, automatic worktree creation used 9.82 GB. Build artifacts make it worse. Bazel, Pants, or Nx monorepos store gigabytes of cache data that multiplies per worktree. One developer found 15 forgotten worktrees “consuming gigabytes” before starting to clean them up. You’ll create merge conflicts with yourself. The GitButler team says it directly: “The worktrees are separate, so you can create merge conflicts between them without knowing.” Parallel agents touching the same files guarantee integration problems. No tool warns you when two agents might edit the same code.

​
Tools that try to help

Several tools have appeared to address these problems. agentree gives you quick worktree creation for AI workflows: agentree -b fix-auth in one terminal, agentree -b ui-fixes in another. git-worktree-runner from CodeRabbit works with Claude, Cursor, Opencode, Copilot, and Gemini through commands like git gtr new my-feature --ai. worktree-cli targets AI workflows with MCP server integration for Claude Code, automatic setup hooks, and file copying for .env handling. gwq shows you a status dashboard of all active worktrees across repositories, plus tmux integration for managing long-running agent processes. For orchestration, ccswarm coordinates multiple agents with specialized pools (Frontend, Backend, DevOps, QA) in worktree-isolated environments. Crystal is a desktop app for running parallel Claude Code and Codex sessions with visual management. The gap no one has closed: no tool connects worktree code isolation with full environment isolation. DevTree tries by combining worktrees with dedicated Dev Containers per branch, including automatic port allocation. But it’s early-stage. Multiple GitHub issues show that worktrees and devcontainers don’t work well together. The .git file format breaks container git operations.

​
Preview environments fix the isolation problem

Local worktrees have one core limitation: they isolate code but not the runtime environment. You get separate file systems but shared ports, databases, and services. Cloud-based preview environments flip this around. Platforms like Upsun create complete, isolated environments for each Git branch. When you push a feature branch, the platform spins up a full production clone: separate application containers, dedicated database instances, unique URLs, and isolated services. This happens through Git integration without manual setup. For parallel AI agent workflows, preview environments eliminate the main friction points:
  • No port conflicts: Each environment runs on its own infrastructure with its own URL.
  • Database isolation by default: Every preview environment gets its own database instance. You can clone production data with sanitization.
  • Dependencies pre-installed: Builds run in the cloud. Each environment has its complete dependency tree.
  • No local disk consumption: Your machine doesn’t store multiple copies of node_modules or build artifacts.
  • Shareable URLs: Give each AI agent’s output a unique URL for testing and review.
The workflow is: create a branch locally, push to trigger environment creation, point your AI agent at that branch’s environment. Each agent operates against a fully isolated stack. This approach has tradeoffs. Environment spin-up takes longer than creating a local worktree (minutes versus seconds). You need network connectivity to test changes. For rapid iteration, local worktrees are faster. But for parallel AI workflows where isolation matters more than speed, preview environments remove entire categories of problems.

​
What an ideal tool would look like

Community discussions keep coming back to the same wishlist. A good multi-agent orchestration tool would combine the speed of local worktrees with the isolation of cloud environments, plus coordination features that neither has. Automatic port allocation without configuration. The tool assigns non-conflicting ports per worktree and updates environment variables. No more manual port arithmetic or .env file management. Per-worktree environment isolation including databases, Docker daemons, and services. This could mean lightweight containers per worktree, or integration with cloud preview environments. The goal is eliminating shared-state conflicts. Merge conflict detection before it’s too late. Before parallel execution begins, the tool analyzes whether tasks are independent or risk touching the same files. During execution, it warns when agents approach the same code regions. AI-assisted resolution helps when conflicts do occur. Context sharing between agents with boundaries. Agents need shared understanding of project architecture and conventions without interfering in each other’s work. A central memory layer maintains project knowledge while keeping task-specific context isolated. A central orchestrator that assigns tasks, monitors progress, and coordinates merges. This layer understands task dependencies, schedules work to minimize conflicts, and helps integrate parallel outputs into coherent commits. Ephemeral environments on demand. Spin up complete isolated stacks (including databases with test data) in seconds. Tear them down when work completes. Local speed with cloud isolation. Visual status and progress tracking. When you’re running five agents at once, you need a dashboard showing what each is working on, how far along they are, and whether any are blocked or failing. VS Code now offer AI-assisted merge conflict resolution, which helps after conflicts happen. But the coordination layer that prevents conflicts in the first place is still missing.

​
Where things are going

Worktrees went from a feature most developers never used to infrastructure for AI-assisted development. The workflow delivers real speed gains: incident.io runs four or five parallel Claude agents routinely, Anthropic documents the pattern officially, and Cursor built it into their product. But the tooling hasn’t caught up. Developers write bash functions, manage ports manually, and run cleanup scripts. The friction adds up: dependency installation, IDE recognition failures, database conflicts, disk space management, merge problems. The next wave of AI coding tools will probably integrate environment isolation directly. For now, worktrees are the best option, even with all their rough edges. You trade operational complexity for the ability to run multiple agents at once.

​
Resources

Want to skip the environment isolation headaches? Upsun’s preview environments create complete, isolated stacks for every Git branch. You get the parallelism benefits of worktrees without the port conflicts, database collisions, or disk space problems.
Last modified on April 14, 2026