Why Git Branches Break AI Coding: The Hidden Cost of Context Switching

The Scenario You've Lived

You're working with two AI agents (Cursor in one window, Claude in another, or two Cursor tabs).

Agent 1: "Let's build authentication"

git checkout -b feature/auth
# Creates: login.ts, auth.ts, jwt.ts, middleware.ts, tests/auth.test.ts...
# 10 files created

Agent 2: "Let's build the dashboard"

git checkout -b feature/dashboard
# Creates: Dashboard.tsx, widgets/, api/, tests/dashboard.test.ts...
# 10 files created

You: "Great! Two features in parallel!"

Reality: Both agents are in the SAME working directory. Both see ALL 20 files.

$ ls src/
auth.ts         # Which branch?
Dashboard.tsx   # Which branch?
jwt.ts          # Which branch?
widgets/        # Which branch?
middleware.ts   # Which branch?

Chaos:

Agent 1: "I see Dashboard.tsx but that's not in my branch..."
Agent 2: "Why is auth.ts here? I'm working on dashboard..."
You: "Which files belong to which feature?"
Git: merge conflict intensifies

Sound familiar?

The Root Cause: Branch Assumptions vs. AI Reality

What Git Branches Assume

Git branches were designed in the 1990s for humans with these characteristics:

✅ One person per working directory
- Your laptop has one workspace
- You switch branches manually
- You know which files belong where
✅ Explicit context switches
- You run git checkout feature/X
- Your mental model updates
- Files appear/disappear visibly
✅ Sequential or coordinated parallel work
- Person A works on feature/auth
- Person B works on feature/dashboard in THEIR OWN workspace
- Each has separate working directories

The AI Agents Reality

AI agents operate differently:

❌ Multiple agents, ONE working directory
- Both Cursor windows share the same workspace
- Both Claude chats reference the same files
- Shared context, shared state
❌ No branch awareness
- Agent doesn't "know" it's on a branch
- Sees all files in working directory
- No mental model of git branching

❌ Files appear/disappear mysteriously

# Agent 1 working on feature/auth
$ git checkout feature/dashboard  # YOU switch branches

# Agent 1's context:
- "Where did auth.ts go?"
- "Why am I seeing Dashboard.tsx?"
- "What happened to the files I was working on?"

The Branch Overhead Tax

Cost 1: Context Switching Kills Productivity

# Scenario: You need to switch from feature/auth to feature/dashboard

$ git checkout feature/dashboard
# Now Agent 1's context is LOST
# - auth.ts disappears from workspace
# - Agent 1 was mid-implementation
# - State is lost
# - Have to re-explain context when you switch back

Time cost: 10-15 minutes per context switch to re-establish what you were doing.

Cost 2: Ambiguous File Ownership

# Working directory with 2 branches merged:
$ ls src/
auth.ts          # feature/auth
Dashboard.tsx    # feature/dashboard  
helpers.ts       # WHICH BRANCH?
utils.ts         # WHICH BRANCH?
api/             # BOTH BRANCHES?

Problem: You can't tell which files belong to which feature without running git log or git show.

Cost 3: Merge Conflicts Multiply

Traditional workflow:

Person A commits to feature/auth in their workspace
Person B commits to feature/dashboard in their workspace
Merge conflicts only when branches merge

AI agent workflow (shared workspace):

Agent 1 creates files on feature/auth
Agent 2 creates files on feature/dashboard
Both in same directory
Switch branches → immediate conflicts
Merge → conflicts even if files don't overlap (workspace state issues)

Cost 4: Lost Agent State

# Agent 1 building auth, mid-implementation
Agent 1: "Let me add password reset..."

# YOU switch branches
$ git checkout feature/dashboard

# Agent 1's state:
- Working files disappeared
- Context lost
- Has to ask "what was I doing?"
- Productivity crater

Failed Workarounds (What People Try)

Workaround 1: "Just work sequentially"

# Agent 1 finishes auth completely
git add . && git commit -m "feat: auth"
git push

# THEN Agent 2 starts dashboard
git checkout -b feature/dashboard

Why it fails:

❌ Kills parallelism
❌ One agent sits idle
❌ Slow, inefficient
❌ Defeats the purpose of multiple agents

Workaround 2: "Use separate working directories"

# Agent 1 workspace
/workspace/agent1/myproject/

# Agent 2 workspace
/workspace/agent2/myproject/

Why it fails:

❌ Complex setup
❌ IDEs don't handle multiple workspaces well
❌ Lost shared context (config, node_modules, etc.)
❌ Sync issues between workspaces
❌ More disk space, more complexity

Workaround 3: "Just deal with the conflicts"

# Accept the chaos, manually resolve everything

Why it fails:

❌ Time-consuming
❌ Error-prone
❌ Frustrating
❌ Wastes the AI productivity gains

The Real Solution: WIP Registry + Trunk-Based Development

The Core Insight

Pre-staging makes file ownership explicit.

Instead of using branches to separate work, we:

Declare file ownership upfront (WIP registry)
Work on trunk (main branch)
Use feature tags in commits (not branch names)

How It Works

Step 1: Register Your Work-In-Progress Files

# Agent 1: "I'm working on authentication"
sc workflow wip register src/auth/*.ts --feature=auth --userid=agent1

# Agent 2: "I'm working on dashboard"
sc workflow wip register src/dashboard/*.tsx --feature=dashboard --userid=agent2

What this does:

Creates .supernal/wip-registry.yaml with file ownership
Pre-stages files (declares ownership BEFORE creating them)
Prevents conflicts (can't register a file someone else owns)

Step 2: Work in Parallel (On Main Branch)

# Both agents work on main branch
$ git branch
* main

# NO BRANCH SWITCHING
# NO CONTEXT LOSS
# NO FILES APPEARING/DISAPPEARING

Agent 1 creates auth files:

# Creates: src/auth/login.ts, src/auth/jwt.ts, etc.
# These files are marked as owned by agent1 in WIP registry

Agent 2 creates dashboard files:

# Creates: src/dashboard/Dashboard.tsx, src/dashboard/widgets/*, etc.
# These files are marked as owned by agent2 in WIP registry

Result: No conflicts. Both agents see all files but KNOW which ones they own.

Step 3: Commit with Feature Tags

# Agent 1 commits
git add src/auth/
git commit -m "feat(auth): implement JWT authentication (REQ-042)"

# Agent 2 commits
git add src/dashboard/
git commit -m "feat(dashboard): add main dashboard view (REQ-043)"

# Both on main branch
# Both committed independently
# No merge conflicts
# Clear feature attribution via conventional commits

Why This Works

✅ Explicit Ownership

$ sc workflow wip list
src/auth/login.ts       (agent1, feature: auth)
src/auth/jwt.ts         (agent1, feature: auth)
src/dashboard/Dashboard.tsx  (agent2, feature: dashboard)

You can see at a glance who owns what.

✅ No Context Switching

Both agents stay on main
No git checkout commands
No files appearing/disappearing
Context preserved

✅ Conflict Prevention

# Agent 2 tries to claim a file Agent 1 owns
$ sc workflow wip register src/auth/login.ts --feature=dashboard --userid=agent2

⚠️ Error: File already WIP-tracked by agent1
Contact agent1 or reassign file ownership

System prevents conflicts proactively.

✅ Parallel Integration

# Agent 1 commits auth
git commit -m "feat(auth): JWT working"

# Agent 2 commits dashboard
git commit -m "feat(dashboard): widgets working"

# Both integrated into main immediately
# No long-lived branches
# Continuous integration

When You Still Need Branches

Branches are still useful for:

1. Long-Running Experiments

# Trying a completely different approach
git checkout -b experiment/new-auth-system

# Spike for 2 days
# If successful, bring findings back to main
# If failed, delete branch

2. External PR Workflows

# Contributing to external repo
git checkout -b fix/bug-123
# Make changes
# Push to your fork
# Open PR to upstream

3. Release Branches

# Preparing v2.0.0 release
git checkout -b release/v2.0.0
# Bug fixes only, no new features
# Merge back to main when released

4. Hotfix Branches

# Production is broken
git checkout -b hotfix/critical-bug
# Fix quickly
# Merge to main and deploy

Key difference: These are intentional, explicit branch uses with clear purpose and known duration.

Real-World Example

Before: Branch Chaos

# YOU (human):
git checkout -b feature/auth
# Agent 1 starts working...

git checkout -b feature/dashboard
# Agent 2 starts working...

git checkout feature/auth  # Back to auth
# Agent 1: "Where's Dashboard.tsx? I was looking at it..."

git checkout feature/dashboard  # Back to dashboard
# Agent 2: "auth.ts disappeared!"

# 30 minutes lost to context switching

After: WIP Registry

# YOU (human):
# Stay on main branch

# Agent 1:
sc workflow wip register src/auth/*.ts --feature=auth --userid=agent1
# Works on auth...
git commit -m "feat(auth): implement JWT"

# Agent 2:
sc workflow wip register src/dashboard/*.tsx --feature=dashboard --userid=agent2
# Works on dashboard...
git commit -m "feat(dashboard): add widgets"

# Both working in parallel
# No context switching
# No conflicts
# Both committed to main

Time saved: 30+ minutes per session. Over a week: hours.

How to Get Started

1. Install WIP Registry Support

# If using Supernal Coding
sc init

# Sets up .supernal/ directory and WIP registry

2. Register Your First WIP Files

# Starting new feature
sc workflow wip register src/myfeature/*.ts --feature=myfeature --requirement=REQ-123

3. Work on Main Branch

# Stay on main
git branch
* main

# Create files, make changes
# Commit with feature tags
git commit -m "feat(myfeature): implement core logic (REQ-123)"

4. Check WIP Status Anytime

# See what you're working on
sc workflow wip list

# See what others are working on
sc workflow wip list --all

# Check for conflicts before claiming files
sc workflow wip check

5. Unregister When Done

# Feature complete
git add src/myfeature/
git commit -m "feat(myfeature): complete implementation (REQ-123)"

# WIP registry auto-unregisters committed files

The Bottom Line

Git branches were designed for humans with separate working directories and explicit context switches.

AI agents operate in shared contexts with implicit, invisible state.

The solution isn't better branch management—it's pre-staging + trunk-based development with explicit ownership.

What You Gain

✅ True parallelism - Multiple agents working simultaneously
✅ Zero context switching - No git checkout commands
✅ Conflict prevention - Can't claim files someone else owns
✅ Continuous integration - Every commit integrates into main
✅ Clear attribution - Feature tags show who did what
✅ Time savings - Hours per week recovered from context switching

What You Lose

❌ Long-lived feature branches (use feature tags instead)
❌ "Safe" parallel work isolation (use WIP registry instead)

The trade is worth it.

Try It Today

# Instead of this (branches):
git checkout -b feature/auth
git checkout -b feature/dashboard
# ...context switching hell

# Do this (WIP registry):
sc workflow wip register src/auth/*.ts --feature=auth
sc workflow wip register src/dashboard/*.tsx --feature=dashboard
git commit -m "feat(auth): implement auth (REQ-042)"
git commit -m "feat(dashboard): implement dashboard (REQ-043)"
# ...parallel development bliss

Your AI agents will thank you.

Learn More

Have you experienced branch chaos with AI agents? How do you handle parallel development? Share your experience in the comments.

Tags: #git-workflow #ai-agents #parallel-development #wip-registry #trunk-based-development #continuous-integration

Status: Published - 2025-12-17