Debugging When You Have 20 AI Agents
More agents means more things that can go wrong. Here's how to stay on top of it.
The New Debugging Problem
Solo coding: one process, one context, all in your head. Agent fleet: 20 processes, 20 contexts, one dashboard. The debugging challenge isn't technical complexity — it's information management. How do you know which of your 20 agents is stuck, looping, or going in the wrong direction?
Signals That an Agent Is in Trouble
- No progress after 20 minutes: If a task that should take 10 minutes shows no code changes after 20, peek at the session. The agent is probably stuck on a compilation error or waiting for input.
- Repeated identical tool calls: An agent in a reasoning loop will keep calling the same tools in the same order. Visible in the peek output.
- Growing token spend with no output: Token tracking in the amux dashboard shows per-session spend. Unusually high spend with no committed code = wasted loop.
- Board task not moving: If a task has been "doing" for 3 hours on a 30-minute estimate, something's wrong.
The Peek-Then-Steer Workflow
amux's live peek feature lets you see any agent's terminal in real time from the dashboard. The debugging workflow:
- Notice a suspicious agent (no progress, high token spend)
- Peek at its session from the dashboard
- Diagnose: stuck prompt? wrong direction? compilation error loop?
- Send a correction message via the dashboard: "Stop. The file is at path/to/file.ts, not path/to/file.js."
- Watch the agent recover and continue
Common Failure Modes and Fixes
| Failure mode | Diagnosis | Fix |
|---|---|---|
| Compilation error loop | Same error in peek output, repeated attempts | Send the correct import path or dependency name |
| Wrong file modified | Git diff shows unexpected changes | Reset branch, re-specify file paths explicitly |
| Context exhausted | amux auto-compact triggered | Self-healed automatically; check output quality after |
| Task too ambiguous | Agent asking many clarifying questions | Send a more specific task description via dashboard |
| Dependency not available | Package not found errors | Run the install command, or tell agent to add to package.json first |
The 5-Agent Monitoring Rule
In practice, actively monitoring more than 5 agents simultaneously is difficult. With 20 agents, the approach is triage: spend the first 10 minutes of each check reviewing all sessions quickly (peek for 30 seconds each), flag the 2-3 that need attention, and intervene only on those. The other 17 run fine on their own.
Get started with amux
Run dozens of Claude Code agents in parallel. Python 3 + tmux. Open source.
git clone https://github.com/mixpeek/amux && cd amux && ./install.sh
amux register myproject --dir ~/Dev/myproject --yolo
amux start myproject
amux serve # → https://localhost:8822