Claude Code Agent Teams

Appearance

SOP-006: Clean Up Teams ​

ID: SOP-006 | Version: 1.0 | Status: Current | Date: 2026-02-12

Fresh 🌱

Gracefully shut down agent teams and clean up shared resources when work is complete.

Overview ​

Proper cleanup ensures resources are freed, sessions are terminated cleanly, and no orphaned processes remain. Always use the lead to initiate cleanup.

Prerequisites ​

  • Agent team is running (SOP-002)
  • Work is substantially complete
  • You're in the lead's session (not a teammate)

Cleanup Workflow ​

Step-by-Step Cleanup ​

Step 1: Verify Work is Complete ​

Before cleanup, check:

Show me the status of all tasks

Expected output:

  • All critical tasks: Completed
  • Remaining tasks: Nice-to-have only
  • No blockers preventing completion
  • Results synthesized or documented

Step 2: Stop New Work ​

Tell the lead:

Stop accepting new work. We're wrapping up.

Lead will:

  • Stop creating new tasks
  • Redirect teammates to finalize current work
  • Begin synthesis/documentation

Step 3: Shut Down Teammates ​

When teammates are finishing:

Ask all teammates to shut down gracefully

Or individual shutdown:

Ask the backend specialist to shut down

Each teammate will:

  1. Receive shutdown request from lead
  2. Respond with approval/rejection:
    • Approve: "Ready to shut down"
    • Reject: "I need 5 more minutes to finish X"
  3. Exit gracefully if approved
  4. Continue working if rejected with explanation

Let teammates finish current tasks - don't force shutdown mid-work.

Step 4: Wait for All to Exit ​

Monitor shutdown progress:

Are all teammates shut down?

Lead will:

  • Check each teammate status
  • Confirm all sessions ended
  • Report any stragglers

Expected output:

✓ Security Specialist: shut down
✓ Backend Developer: shut down
✓ Frontend Developer: shut down
All teammates have exited.

Step 5: Clean Up Team ​

When all teammates are shut down:

Clean up the team

Claude (the lead) will:

  1. Verify all teammates are offline
  2. Remove shared task list
  3. Delete team configuration
  4. Free resources
  5. Confirm cleanup complete

Output:

✓ Team 'project-x-review' cleanup initiated
✓ Verified all 3 teammates shut down
✓ Task list removed
✓ Team resources freed
✓ Cleanup complete

Step 6: Verify Cleanup ​

Check that team is really gone:

Show me the current team status

Expected:

No active team.

Or check filesystem:

bash
# macOS/Linux
ls ~/.claude/teams/

# Windows PowerShell
ls $env:USERPROFILE\.claude\teams\

Team folder should be gone.

Handling Shutdown Issues ​

Teammate Won't Shut Down ​

Can the backend specialist exit the team?

If they refuse:

  1. Get explanation (they may have critical work)
  2. Allow more time: "We can wait 5 minutes"
  3. Or force exit (last resort):
    Force shutdown the backend specialist

Cleanup Fails with Error ​

If cleanup doesn't complete:

What's preventing cleanup? Try again.

Common issues:

  • Teammate still running → shut them down first
  • Permissions issue → use dangerously-skip flag
  • Orphaned session → manual cleanup (see below)

Manual Cleanup for Stuck Teams ​

If automated cleanup fails:

bash
# List all teams
ls ~/.claude/teams/

# Remove specific team (replace with actual name)
rm -rf ~/.claude/teams/my-team-name

# Or remove all team files
rm -rf ~/.claude/teams/

tmux cleanup (if using split panes):

bash
# List all tmux sessions
tmux ls

# Kill the team session
tmux kill-session -t session-name

Post-Cleanup ​

Save Results ​

Before cleanup, save important findings:

Save all findings to docs/FINDINGS.md

Claude should:

  • Compile all teammate work
  • Synthesize discoveries
  • Document decisions
  • Write summary

Archive Session ​

Create a transcript or log:

bash
# macOS/Linux - save terminal history
history > team-session-log.txt

# Or copy Claude Code transcript
cp ~/.claude/logs/... backup/

Lessons Learned ​

After first team cleanup, document:

  • What worked well
  • What was challenging
  • How to improve next time
  • Best team configuration for this type of work

Best Practices ​

Natural Shutdown Timing ​

❌ Too early:

Clean up when only 60% done

(Valuable work interrupted)

✅ Just right:

Wait for key findings documented, all tasks completed or properly closed

Get Final Summary First ​

Before cleanup:

Synthesize all findings into a comprehensive summary document

This ensures no discoveries are lost.

Graceful Over Forced ​

Graceful shutdown (preferred):

Ask teammates to shut down
  • Clean exit
  • Proper resource cleanup
  • No orphaned processes

Force shutdown (last resort):

Force shutdown all teammates
  • Fast but messy
  • May leave temporary files
  • Risk of incomplete work loss

Document Everything Before Cleanup ​

Before we clean up, please:
1. Save all findings to RESULTS.md
2. Document any open questions in TODO.md
3. Include recommended next steps

Verification Checklist ​

✓ Work documented

  • Results saved to files
  • Findings compiled
  • Summary written

✓ All teammates shut down

  • None showing in Shift+Up/Down cycling
  • Lead confirms all gone
  • No orphaned sessions

✓ Team cleanup completed

  • No errors during cleanup
  • Lead confirms team removed
  • Team folder gone from ~/.claude/teams/

✓ Resources freed

  • No orphaned tmux sessions (tmux ls shows none)
  • Terminal responsive
  • No stray processes

✓ Session still responsive

  • Can type new commands
  • Lead isn't stuck in cleanup loop
  • Ready for next session or team

Troubleshooting ​

Q: "Cleanup failed: teammates still running" A:

  1. Manually shut down: Ask all teammates to shut down
  2. Wait 10 seconds for graceful exit
  3. Force if needed: Force shutdown all teammates
  4. Then try cleanup again

Q: Cleanup hung/stuck A:

  1. Kill stuck lead session: Ctrl+C
  2. Manual cleanup: rm -rf ~/.claude/teams/team-name
  3. Restart: claude starts fresh

Q: "Permission denied" during cleanup A: Use flag on startup:

claude --dangerously-skip-permissions

Q: Orphaned tmux session remains A:

bash
tmux ls  # Find session name
tmux kill-session -t session-name

Q: Lost important work during cleanup A:

  1. Check terminal history
  2. Check ~/.claude/logs/ for session transcripts
  3. Recovery may not be possible - lesson for future

Prevention Tips ​

Always Save Before Cleanup ​

Document all findings, save to files, then clean up

Create Backups ​

bash
# Backup team config before cleanup
cp -r ~/.claude/teams/ backup-teams/

# Backup chat logs
cp -r ~/.claude/logs/ backup-logs/

Test Cleanup Process ​

First team cleanup:

  1. Do it with low-stakes work
  2. Verify all cleanup steps work
  3. Note any issues
  4. Document your team's cleanup procedure

See Also ​