9. Troubleshooting

Common Issues

Issue: Agents not spawning

Symptoms:

• Agent teams prompt accepted but no teammates created
• Only team lead session running

Causes:

1. Feature flag not set correctly
2. Model not Opus 5 (teams require Opus)
3. Task not complex enough (Claude decided single agent sufficient)

Solutions:

# Verify flag
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS  # Should output "1" or "true"

# Check settings
cat ~/.claude/settings.json | grep agentTeams  # Should be true

# Force model
/model opus

# Explicit request
"Spawn 3 agents for this task (team lead + 2 teammates)"

Issue: Merge conflicts overwhelming

Symptoms:

• Many git conflicts after agents complete
• Manual resolution required frequently

Causes:

• Poor task decomposition (overlapping file sets)
• Write-heavy task (multiple agents modifying shared files)

Solutions:

Prevention:
1. Clear boundaries: Non-overlapping file assignments
2. Interface-first: Define contracts before implementation
3. Single-writer: One agent writes shared files, others read

Recovery:
1. Revert: git reset --hard before-agent-teams
2. Sequential: Re-implement with single agent
3. Human merge: Manually resolve conflicts (git mergetool)

Issue: High token costs

Symptoms:

• Token usage 3x+ higher than expected
• Budget exhausted quickly

Causes:

• Over-spawning agents (3+ agents for simple tasks)
• Long-running sessions (agents idle)
• Large context per agent (1M tokens × 3)

Solutions:

Immediate:
1. Kill extra agents: Shift+Down, exit agent session
2. Reduce scope: Narrow task boundaries
3. Switch to single agent: /model sonnet (cheaper)

Long-term:
1. Cost monitoring: Track token usage per session
2. Lazy spawning: Only spawn when needed
3. Progressive escalation: Start small, scale up if needed

Issue: Agents stuck/hanging

Symptoms:

• One agent finishes, others still processing for long time
• No progress updates

Causes:

• Imbalanced task distribution (one agent has 80% of work)
• Agent waiting for dependency (sequential coupling)
• Bug in git coordination (rare)

Solutions:

# Navigate to stuck agent
Shift+Down  # Switch to agent

# Check status
"What are you working on? Progress update?"

# Manual takeover if needed
"Stop current task, report findings so far"

# Kill and redistribute
Exit agent → Team lead redistributes task

Issue: Inconsistent results across agents

Symptoms:

• Agent 1 says "No issues", Agent 2 finds 10 bugs (same codebase)
• Conflicting recommendations

Causes:

• Different context windows (agents saw different files)
• Ambiguous instructions (agents interpreted differently)
• Model variability (stochastic outputs)

Solutions:

Prevention:
1. Explicit instructions: "All agents: Check for SQL injection"
2. Shared context: Point all agents to same reference docs
3. Validation: Human reviews all agent outputs

Recovery:
1. Reconciliation: "Compare Agent 1 and Agent 2 findings, resolve conflicts"
2. Third opinion: Spawn Agent 3 to arbitrate
3. Human decision: You choose which agent's recommendation to follow

Navigation Problems

Can't find agent sessions:

# List all sessions
claude --list

# Filter for agent sessions
claude --list | grep agent

# Resume specific agent