Troubleshooting Guide

Problems, symptoms, and solutions organized by issue type.

Fresh 🌱

Quick Symptom Lookup

Symptom	Likely Cause	Quick Fix
Teammates won't appear	Task too simple OR not enabled	Enable agent teams (SOP-001)
Permission denied	Permissions not granted	Pre-approve or use --dangerously-skip-permissions
Messages not arriving	Teammate offline	Check Shift+Down, respawn if needed
Split panes broken	tmux not installed	Install tmux OR use in-process mode
Team stuck on cleanup	Teammates still running	Shut down each teammate first
Tasks not updating	UI lag	Refresh view or tell lead to check
Ctrl+T not working	Wrong mode	Verify in lead session (not teammate)
Can't exit session	Escape not working	Try Escape twice, or Ctrl+C

Enabling Agent Teams

Problem: "Agent teams feature not enabled"

Symptoms:

• Claude doesn't recognize agent team commands
• "Agent teams not enabled" message
• Can't spawn teammates

Solutions:

1. Check setting is saved:

   cat ~/.claude/settings.json | grep CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

2. Add to settings.json if missing:

   {
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
     }
   }

3. Restart Claude Code:

   pkill -f "claude"
   claude

4. Verify: Try creating team: Create an agent team

If still not working:

• Check JSON syntax (no trailing commas)
• Verify file is at ~/.claude/settings.json
• Try environment variable instead:

  export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
  claude

See SOP-001: Enable Agent Teams

Teammates Not Appearing

Problem: Teammates don't show up after creation request

Symptoms:

• Ask for team, nothing happens
• No teammates visible in Shift+Down cycling
• Task list empty

Diagnosis:

1. Task might be too simple:

   Claude analyzes whether task needs parallelization
   If simple enough for 1 agent, Claude won't create team

2. Check in background:

   In in-process mode, teammates might be running
   Try Shift+Down multiple times to cycle

3. Verify team creation:

   Check ~/.claude/teams/ directory
   Should contain team folder

Solutions:

1. Make request more explicit:

   Create an agent team with 3 teammates to [task]

2. Describe team structure:

   Create an agent team:
   - One teammate for X
   - One teammate for Y
   - One teammate for Z

3. Give more context:

   This is a complex project. Create an agent team with 4 teammates
   to handle [detailed task description with requirements]

4. Check if already running:

   • In-process: Shift+Down cycles through all
   • Split panes: Each has its own pane
   • If truly nothing, try creating again

Last resort:

# Kill any stuck Claude processes
pkill -f "claude"

# Start fresh
claude

See SOP-002: Create Your First Team

Permission Errors

Problem: "Permission denied" during team operations

Symptoms:

• Errors spawning teammates
• Can't execute commands
• Can't write files

Common Causes:

1. Permissions not pre-approved
2. File system permissions issue
3. Tool access restricted

Solutions:

Option 1: Pre-approve operations

Edit ~/.claude/settings.json:

{
  "mode": "bypassPermissions"
}

Restart Claude Code.

Option 2: Skip all permissions for session

claude --dangerously-skip-permissions

Option 3: Approve each permission

Claude will prompt for each operation. Click "Approve" when asked.

Option 4: Adjust team permissions

After spawning teammates, adjust individual permissions:

Change [teammate] to bypassPermissions mode

Display Mode Issues

Problem: Display mode not working as expected

Symptoms (In-Process Mode):

• Shift+Up/Down not cycling through teammates
• Ctrl+T not showing task list
• Can't enter teammate session

Solutions:

1. Verify in-process mode:

   claude --teammate-mode in-process

2. Check terminal supports shortcuts:

   • Some terminals override Shift+Up/Down
   • Try different terminal if not working
   • macOS Terminal, iTerm2, VSCode, Windows Terminal all usually work

3. Try typing instead:

   Show me the task list
   Tell me the current status
   What's the next teammate?

Symptoms (Split Panes Mode):

• "tmux not found" error
• Panes not appearing
• Click not working

Solutions:

1. Install tmux:

   # macOS
   brew install tmux
   
   # Ubuntu/Debian
   sudo apt-get install tmux
   
   # Fedora
   sudo dnf install tmux
   
   # Verify
   tmux --version

2. Install it2 for iTerm2:

   pip install it2

   Then enable Python API:

   • Open iTerm2 → Settings → General
   • Check "Enable Python API"
   • Restart iTerm2

3. Switch back to in-process:

   claude --teammate-mode in-process

4. Try auto mode:

   {
     "teammateMode": "auto"
   }

See SOP-003: Configure Display Modes

Message Delivery Issues

Problem: Messages not reaching teammates

Symptoms:

• Tell teammate to do something, they don't respond
• Broadcast doesn't reach everyone
• Messages disappear

Solutions:

1. Verify teammate is active:

   Shift+Down (in-process mode)
   Can you see the teammate?

2. Check if teammate is stuck:

   • They may be in middle of long task
   • Give them time to finish
   • Or ask them to stop:

   Tell [teammate] to pause

3. Send message again:

   Tell [teammate]: [message]

4. Try direct interaction:

   • In-process: Shift+Down + Enter
   • Type message directly
   • Escape to return

5. Respawn if unreachable:

   The teammate seems stuck. Shut down [teammate]
   Spawn replacement teammate for [task]

File and Permissions Issues

Problem: Teammates can't edit files or run commands

Symptoms:

• "Cannot edit file" errors
• "Cannot execute command" errors
• Teammates stuck

Solutions:

1. Check delegate mode:

   • If delegate mode enabled, lead can't edit
   • Switch: Shift+Tab to toggle
   • Or tell lead: Exit delegate mode

2. Pre-approve permissions:

   {
     "mode": "bypassPermissions"
   }

3. Use skip flag:

   claude --dangerously-skip-permissions

4. Change individual teammate:

   Set [teammate] to bypassPermissions mode

5. Check file ownership:

   # See if Claude can access files
   ls -la [file]
   
   # May need to adjust permissions
   chmod 644 [file]

Task List Issues

Problem: Tasks not showing or not updating

Symptoms:

• Ctrl+T doesn't show tasks
• Tasks show wrong status
• Can't assign tasks
• Tasks stuck on "pending"

Solutions:

1. Verify in lead session:

   • Task list only visible to lead
   • Make sure you're in lead's session
   • Try Shift+Down back to lead

2. Refresh view:

   Show me the task list

3. Check task file manually:

   ls ~/.claude/tasks/[team-name]/
   cat ~/.claude/tasks/[team-name]/task-1.json

4. Tasks stuck on pending:

   Why isn't this task being claimed?
   Assign task #3 to [teammate]

5. Manual status update (if stuck):

   Manually mark task #5 as complete

Team Cleanup Issues

Problem: Can't clean up team

Symptoms:

• Cleanup command hangs
• "Teammates still running" error
• Team folder remains after cleanup
• Orphaned processes

Solutions:

1. Shut down all teammates first:

   Ask all teammates to shut down

2. Wait for graceful shutdown:

   • Give them 10-15 seconds
   • They may need to finish current task

3. Force shutdown if needed:

   Force shutdown all teammates

4. Then clean up:

   Clean up the team

5. Manual cleanup if stuck:

   # Remove team directory
   rm -rf ~/.claude/teams/[team-name]
   
   # Remove tasks
   rm -rf ~/.claude/tasks/[team-name]
   
   # Kill orphaned tmux session (if split panes)
   tmux ls
   tmux kill-session -t [session-name]

6. Kill stuck Claude process:

   pkill -9 -f "claude"

See SOP-006: Clean Up Teams

Performance Issues

Problem: Team running slowly

Symptoms:

• Commands taking long time
• Teammates slow to respond
• Messages delayed
• High CPU/memory usage

Solutions:

1. Reduce team size:

   • Fewer teammates = faster
   • Try 2-3 instead of 5

2. Use faster model:

   Create team with Haiku teammates

3. Split complex work:

   • Multiple teams in sequence
   • Better than one large team

4. Check system resources:

   # macOS/Linux
   top
   
   # Windows
   tasklist

5. Close other apps:

   • Free up RAM
   • Reduce CPU contention

6. Reduce task scope:

   • Fewer teammates working
   • on smaller subsets

Lead Doing Work Instead of Delegating

Problem: Lead implements instead of coordinating

Symptoms:

• Lead editing code instead of delegating
• Teammates idle while lead works
• Lead becomes bottleneck

Solutions:

1. Tell lead explicitly:

   Wait for your teammates to complete their tasks before proceeding

2. Enable delegate mode:

   Press Shift+Tab

3. Assign work more specifically:

   Assign task #3 to [teammate]
   Don't implement it yourself - let them do it

4. Focus lead on synthesis:

   Stop working on code. Coordinate your teammates instead.
   Check on each one's progress.

See Delegate Mode Workflow

Keyboard Shortcuts Not Working

Problem: Shortcuts don't respond

Symptoms:

• Shift+Up/Down doesn't cycle
• Ctrl+T doesn't show tasks
• Shift+Tab doesn't toggle delegate
• Enter doesn't enter teammate session

Diagnosis:

1. Terminal may intercept shortcuts:

   • Some terminals use these for own functions
   • VS Code terminal is common conflict
   • Try different terminal

2. You may not be in right mode:

   • Some shortcuts only work in certain modes
   • Shift+Up/Down only in-process mode
   • Ctrl+T only in lead session

3. Timing issue:

   • Give Claude time to process
   • Double-check you're in right session

Solutions:

1. Try different terminal:

   • macOS: Native Terminal, iTerm2
   • Linux: GNOME Terminal, Konsole
   • Windows: Windows Terminal, PowerShell

2. Use commands instead:

   Show me the task list (instead of Ctrl+T)
   What teammates are active? (instead of Shift+Down)

3. Verify mode:

   In-process mode: Shift+Up/Down, Ctrl+T, Enter, Escape work
   Split panes mode: Click panes, use tmux shortcuts
   Delegate mode: Shift+Tab to toggle

Stuck Teammates

Problem: Teammate not responding or stuck

Symptoms:

• Teammate not responding to messages
• Appears hung or stuck
• Won't move to next task
• Long time without progress

Solutions:

1. Try to communicate:

   Tell [teammate]: Are you still working?

2. Give them time:

   • Some tasks take longer
   • Wait a few minutes for response

3. Enter their session:

   Shift+Down to find them
   Enter to see what they're doing
   Escape to go back

4. Give new instruction:

   Tell [teammate]: Let's try a different approach

5. Force interrupt:

   Escape key while in their session
   Stops current action/turn

6. Shutdown and replace:

   Shut down [teammate]
   Spawn new teammate for same task

7. Check error state:

   [In teammate's session, look for error messages]

Data Consistency Issues

Problem: Inconsistent team state

Symptoms:

• Task shows "completed" but work isn't done
• Task dependencies don't resolve
• Teammate states don't match
• File conflicts between teammates

Solutions:

1. Check task manually:

   cat ~/.claude/tasks/[team]/task-N.json

2. Revert if incorrect:

   Reopen task #5 (it wasn't actually complete)

3. Avoid file conflicts:

   • Assign different files to different teammates
   • Don't have 2 teammates edit same file

4. Set clear task boundaries:

   • Each teammate owns distinct work
   • Clear interfaces between modules

5. Manual resync if needed:

   rm -rf ~/.claude/tasks/[team]
   rm -rf ~/.claude/teams/[team]
   # Rebuild team

Contact & Further Help

If you encounter issues not covered here:

1. Check relevant SOP:

   • SOP-001: Enable Agent Teams
   • SOP-002: Create Your First Team
   • SOP-003: Display Modes

2. Review workflow guide:

   • Parallel Code Review
   • Competing Hypotheses

3. Check architecture:

   • Architecture Reference

4. Ask the chat widget:

   • Use "Ask the Docs" widget (bottom right)
   • Describe your issue
   • Get instant help

See Also

• Commands Reference
• Keyboard Shortcuts
• Architecture
• SOPs