Parallel Development with Antigravity and git worktree — A Practical Multi-Workspace Guide

The Real Cost of Branch Switching

You're deep into building a new feature when a production bug drops into your lap. The familiar dance begins: git stash, git checkout hotfix, fix the bug, switch back, git stash pop. Except this time the stash conflicts with your working changes, and the node_modules directory needs a fresh install because the hotfix branch uses a different dependency version. Twenty minutes gone, and you've lost the mental context of what you were building.

Git worktrees paired with Antigravity's multi-workspace feature eliminate this problem entirely. Each branch gets its own physical directory, its own node_modules, and its own AI agent with independent conversation history. No stashing, no reinstalling, no context loss.

This guide walks through the practical setup and workflow patterns that make parallel development work in real projects.

What git worktree Actually Does

Git worktree creates additional working directories from a single repository. Unlike git clone, worktrees share the same .git object store, saving disk space and keeping commit history instantly accessible across all branches.

# Starting from your main project directory
cd ~/projects/my-app
 
# Create a worktree for a hotfix branch
git worktree add ../my-app-hotfix hotfix/payment-bug
 
# Create a worktree for a feature branch
git worktree add ../my-app-feature feature/user-dashboard

You now have three independent directories:

• ~/projects/my-app — main branch (original directory)
• ~/projects/my-app-hotfix — hotfix branch
• ~/projects/my-app-feature — feature branch

Each has its own file tree. Running npm install in one has zero effect on the others. This is the fundamental difference from git stash plus git checkout.

Connecting Worktrees to Antigravity Workspaces

Antigravity's Agent Manager lets you open any directory as a workspace through the "Open Workspace" option in the left pane. Opening each worktree directory as a separate workspace gives you isolated AI agents operating on independent branches.

Step 1: Create Worktrees and Install Dependencies

# From the project root
cd ~/projects/my-app
 
# Feature branch worktree
git worktree add ../my-app-feat feature/new-api
cd ../my-app-feat
npm install  # Isolated node_modules for this worktree
 
# Hotfix branch worktree
cd ~/projects/my-app
git worktree add ../my-app-fix hotfix/auth-error
cd ../my-app-fix
npm install

Step 2: Open Each Worktree in Antigravity

In Agent Manager, add each worktree directory as a workspace. Rename them for clarity:

Workspace 1: my-app-feat  → "New API Development"
Workspace 2: my-app-fix   → "Auth Bug Fix"
Workspace 3: my-app       → "Main (Review & Merge)"

Step 3: Scope Each Agent with AGENTS.md

Place a different AGENTS.md in each worktree to constrain what the agent can modify. This is a technique that's difficult to replicate with normal branch switching since the file would need to change every time you switch contexts.

<\!-- my-app-feat/AGENTS.md -->
# Agent Instructions
 
## Context
Implementing new REST API endpoints. Follow the OpenAPI spec strictly.
 
## Rules
- Only modify files under src/api/
- Always add tests in src/__tests__/api/
- Do not touch existing endpoints

<\!-- my-app-fix/AGENTS.md -->
# Agent Instructions
 
## Context
Emergency fix for authentication flow bug. Minimal changes only.
 
## Rules
- Only change files directly related to the bug
- No refactoring
- Add tests demonstrating the fix

The key benefit here is reducing unintended side effects. An agent working on a hotfix won't accidentally refactor unrelated code because its scope is explicitly limited to the bug at hand.

A Three-Workspace Pattern for Solo Development

The setup I use daily is a "develop, fix, review" three-workspace layout.

#\!/bin/bash
# setup-worktrees.sh — place in project root
PROJECT_ROOT=$(pwd)
PROJECT_NAME=$(basename "$PROJECT_ROOT")
 
setup_worktree() {
  local branch=$1
  local suffix=$2
  local dir="../${PROJECT_NAME}-${suffix}"
  
  if [ -d "$dir" ]; then
    echo "✓ ${dir} already exists"
    return
  fi
  
  # Create the branch if it doesn't exist
  git branch "$branch" 2>/dev/null || true
  git worktree add "$dir" "$branch"
  
  # Install dependencies if package.json exists
  if [ -f "${dir}/package.json" ]; then
    cd "$dir" && npm install && cd "$PROJECT_ROOT"
  fi
  
  echo "✓ ${dir} set up successfully"
}
 
setup_worktree "develop" "dev"
setup_worktree "hotfix/current" "fix"
 
echo ""
echo "Open these directories in Antigravity as separate workspaces:"
echo "  1. ${PROJECT_ROOT}         → main (review & merge)"
echo "  2. ../${PROJECT_NAME}-dev  → develop (feature work)"
echo "  3. ../${PROJECT_NAME}-fix  → hotfix (urgent fixes)"

How Each Workspace Functions

Workspace 1 (develop): The primary development area. New features, UI work, and test additions happen here with AI agent assistance. Use Plan Mode for breaking down larger tasks into incremental steps.

Workspace 2 (hotfix): Dedicated to production bug fixes. The agent is constrained via AGENTS.md to make minimal, targeted changes. Once the fix is verified, it merges to main and deploys immediately.

Workspace 3 (main): The review and merge hub. Pull requests from other worktrees are reviewed here, with AI-assisted code review. Running git log --oneline --all gives you a bird's-eye view of progress across all branches.

Three Rules for Preventing Merge Conflicts

Merge conflicts are the biggest risk in parallel development. These three rules dramatically reduce their frequency.

Rule 1: Assign File Ownership by Worktree

# In AGENTS.md, restrict modifiable paths per worktree
 
# develop worktree
- Only modify files under src/features/
 
# hotfix worktree
- Only modify files under src/lib/auth/

Never edit the same file in two worktrees simultaneously. This is the single most effective conflict prevention measure.

Rule 2: Change Shared Files Only in Main

Files that multiple features depend on—package.json, config files, shared utilities—should only be modified in the main workspace. After changing them, pull updates into each worktree:

# In each worktree, periodically pull main's changes
cd ~/projects/my-app-dev
git fetch origin main
git rebase origin/main

Rule 3: Merge in Short Cycles

Long-lived worktrees accumulate drift from main, increasing conflict risk. Merge hotfixes within the same day. Merge feature branches within three days. If a feature takes longer, rebase onto main regularly.

Before and After: The Workflow Difference

Before (stash workflow):

1. git stash current work — risky if you have unstaged changes
2. git checkout hotfix — branch switch
3. npm install — dependency reinstall (30 seconds to several minutes)
4. Fix the bug, commit, push
5. git checkout feature — switch back
6. git stash pop — stash conflicts are possible
7. npm install — reinstall again

Total overhead: 10–15 minutes per context switch, plus mental recovery time.

After (worktree + Antigravity):

1. Click the hotfix workspace in Agent Manager
2. Describe the bug fix — agent makes the change, commits, pushes
3. Click back to the development workspace and continue where you left off

Total overhead: 2–3 minutes. No stashing, no reinstalling, no re-explaining context to the AI.

The biggest win isn't the time saved—it's the preserved mental state. Each workspace's AI agent retains its own conversation history, so you never have to re-explain "what we were working on" when switching back.

Important Constraint: One Branch Per Worktree

Git enforces a hard rule: the same branch cannot be checked out in multiple worktrees simultaneously.

# This will fail
git worktree add ../my-app-2 main
# fatal: 'main' is already checked out at '/home/user/projects/my-app'

This constraint is a safety mechanism. If the same branch were edited in two places, determining which commits take precedence becomes ambiguous. If you need to work with the same code in two contexts, create a new branch from it and merge afterward.

Worktree Lifecycle Management

Worktrees that accumulate without cleanup become a management burden. Remove them promptly after merging.

# List all active worktrees
git worktree list
# Output:
# /home/user/projects/my-app       abc1234 [main]
# /home/user/projects/my-app-dev   def5678 [develop]
# /home/user/projects/my-app-fix   ghi9012 [hotfix/current]
 
# Remove a merged hotfix worktree
cd ~/projects/my-app
git worktree remove ../my-app-fix
 
# Delete the branch if no longer needed
git branch -d hotfix/current

Remember to close the corresponding Antigravity workspace as well. A workspace pointing to a deleted directory will throw errors.

Automating Setup with git-worktree-runner

For a more streamlined experience, git-worktree-runner automates worktree creation, config file copying, dependency installation, and editor integration in a single command.

# Install
git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner
chmod +x wt.sh
 
# Create a new worktree with automatic setup
./wt.sh create feature/payment-v2
 
# Open it in Antigravity as a workspace
./wt.sh open feature/payment-v2 --editor antigravity

The tool automatically copies .env, .vscode/settings.json, and other configuration files into the new worktree, eliminating the need to reconfigure each workspace manually.

What to Do Next

Try creating a single worktree right now. Pick an existing project, create a hotfix worktree with git worktree add, and open it as a separate workspace in Antigravity. Once you experience switching between workspaces without stashing or reinstalling, you won't go back.

For setting up project-specific agent rules in each worktree, see Antigravity context control techniques. If merge conflicts do occur, the AI-assisted git conflict resolution guide covers how to resolve them efficiently. And for further workspace management tips, Antigravity workspace optimization covers additional techniques for keeping your multi-workspace setup fast and organized.