Debugging Agent Issues

Goal

Diagnose agent failures, rate limits, cost overruns, and network issues using RANO, CAUT, WA, and CASS together.

The Debugging Toolkit

When agents stop working, you need to answer: Is it a rate limit? A network issue? A cost overrun? A bug in the prompt?Four tools give you complete observability.

RANO

Network traffic — see every API call

CAUT

Cost tracking — per-session spend analysis

WA

Terminal state — pattern detection across panes

CASS

History — search past sessions for solutions

Agent Debug War Room

Step through 6 real debugging scenarios. Click “Diagnose” to analyze each one.

Infinite Loop Detected

Scenario 1/6

Agent State

Context Window--%

Input tokens--

Output tokens--

Error Trace

Agent Loopagent/main.ts

runLoop() called 47 times without progress

Tool Calltools/edit.ts

Same edit applied and reverted repeatedly

File Systemfs/write.ts

Write succeeds but lint fails

Lint Checklint/eslint.ts

Error persists after each edit attempt

Model vs Reality

Agent Believes

I need to fix this lint error

Let me edit the file...

Edit applied successfully

Running lint check...

Lint failed. Let me try again...

(repeats 47 times)

Reality

Agent applies correct fix

BUT: another rule conflicts

Lint reports different error

Agent reverts to original approach

Same conflict triggers again

Context window filling with retries

Ranked Fixes

Kill loop and reset context--%

wa robot send pane-1 "/clear"

Add eslint-disable for conflicting rule--%

Agent: "Add eslint-disable comment"

Break task into two separate steps--%

ntm send myproject --pane=1 "Fix only the type error first"

Session Log

14:02:01Agent started task: fix lint errors

14:02:15Edit applied to src/utils.ts

14:02:18Lint check failed: no-unused-vars

14:02:22Agent retrying edit...

14:03:45Loop detected: 12 identical edits

14:05:30Context 97% full, 47 turns with no progress

Rate Limit Diagnosis

Rate limits are the most common agent failure. Here's how to diagnose and work around them.

Rate Limit Workflow

# Step 1: Check if RANO sees 429 responses
rano status
# Look for: HTTP 429 Too Many Requests
# Step 2: Check which provider is throttling
caut breakdown
# Shows per-provider token consumption
# Step 3: Check WA for rate limit patterns across panes
wa robot events --rule-id "claude_code.rate_limit" --unhandled-only
# Step 4: Rotate to a fresh account
caam status --verbose
caam rotate
# Step 5: Check CASS for how you solved this before
cass search "rate limit workaround rotation" --limit 3

Pro Tip

If you see 429s from RANO but CAUT shows low token usage, you're likely hitting requests-per-minute limits, not token limits. Space out your requests or use CAAM to rotate accounts.

Network Debugging

RANO intercepts all agent API traffic, letting you see exactly what's happening at the network level.

Show active connections and recent errors

Filter to just failed requests

Filter by API provider

Find requests taking over 10 seconds

Find server errors from providers

Error Pattern Guide

# Common patterns and what they mean:
# Lots of 429s → Rate limiting (use CAAM to rotate)
# Connection timeouts → Network/DNS issue (check VPS connectivity)
# 500/503 errors → Provider outage (switch to different provider)
# Slow responses (>30s) → Provider overloaded (try during off-peak)
# SSL errors → Certificate issue (check system time/certs)

Cost Investigation

When costs spike unexpectedly, use CAUT to find the expensive sessions and RANO to see what they're doing.

Cost Analysis

# Find your most expensive sessions today
caut sessions --sort cost --limit 5
# Compare against yesterday
caut summary --period 1d
caut summary --period 2d  # includes yesterday
# Check token efficiency (high input/low output = wasted context)
caut efficiency
# Drill into a specific session's API calls
rano log --session <session-id> --verbose
# Common cost culprits:
# 1. Agents re-reading large files repeatedly
# 2. Long context windows with low-value content
# 3. Agents stuck in retry loops
# 4. Using Opus when Sonnet would suffice

Warning

If an agent's input tokens are 10x its output tokens, it's probably stuffing too much context. Use TRU to compress source files before feeding them to agents.

Stuck Agent Detection

WA detects when agents go silent. An idle pane usually means the agent is waiting for approval, hit an error, or is genuinely stuck.

Stuck Agent Diagnosis

# Check all pane states
wa robot state | jq '.data.panes[] |
  select(.idle_seconds > 120) |
  {id, title, idle_seconds, last_output_preview}'
# Get the last 50 lines from a stuck pane
wa robot get-text <pane_id> --tail 50
# Search for error patterns in pane output
wa search "error|failed|panic|traceback" --pane <pane_id>
# Check if agent is waiting for SLB approval
wa robot events --rule-id "claude_code.waiting_approval"
# Force-send a nudge to wake up a stuck agent
wa robot send <pane_id> "Continue with the task"

Learning from History

CASS stores all past agent sessions. When you encounter a new problem, search for how you (or another agent) solved it before.

Historical Search

# Search for how a specific error was resolved
cass search "ECONNREFUSED anthropic API fix" --limit 5
# Find sessions that worked with a specific tool
cass search "successfully deployed with docker" --limit 3
# Search across all agent types
cass search "memory leak node process" --robot --limit 5
# Use CM to check if there's a playbook rule
cm context "debugging API connection failures" --json

Quick Diagnosis

RANO status + CAUT summary = instant health check

Deep Investigation

WA events + RANO logs = full request trace

Cost Audit

CAUT breakdown + session drill-down = spend accountability

Pattern Recognition

CASS history + CM playbook = never solve twice

# Step 1: Check if RANO sees 429 responses

rano status

# Look for: HTTP 429 Too Many Requests

# Step 2: Check which provider is throttling

caut breakdown

# Shows per-provider token consumption

# Step 3: Check WA for rate limit patterns across panes

wa robot events --rule-id "claude_code.rate_limit" --unhandled-only

# Step 4: Rotate to a fresh account

caam status --verbose

caam rotate

# Step 5: Check CASS for how you solved this before

cass search "rate limit workaround rotation" --limit 3

# Common patterns and what they mean:

# Lots of 429s → Rate limiting (use CAAM to rotate)

# Connection timeouts → Network/DNS issue (check VPS connectivity)

# 500/503 errors → Provider outage (switch to different provider)

# Slow responses (>30s) → Provider overloaded (try during off-peak)

# SSL errors → Certificate issue (check system time/certs)

# Find your most expensive sessions today

caut sessions --sort cost --limit 5

# Compare against yesterday

caut summary --period 1d

caut summary --period 2d # includes yesterday

# Check token efficiency (high input/low output = wasted context)

caut efficiency

# Drill into a specific session's API calls

rano log --session <session-id> --verbose

# Common cost culprits:

# 1. Agents re-reading large files repeatedly

# 2. Long context windows with low-value content

# 3. Agents stuck in retry loops

# 4. Using Opus when Sonnet would suffice

# Check all pane states

wa robot state | jq '.data.panes[] |

select(.idle_seconds > 120) |

{id, title, idle_seconds, last_output_preview}'

# Get the last 50 lines from a stuck pane

wa robot get-text <pane_id> --tail 50

# Search for error patterns in pane output

wa search "error|failed|panic|traceback" --pane <pane_id>

# Check if agent is waiting for SLB approval

wa robot events --rule-id "claude_code.waiting_approval"

# Force-send a nudge to wake up a stuck agent

wa robot send <pane_id> "Continue with the task"

# Search for how a specific error was resolved

cass search "ECONNREFUSED anthropic API fix" --limit 5

# Find sessions that worked with a specific tool

cass search "successfully deployed with docker" --limit 3

# Search across all agent types

cass search "memory leak node process" --robot --limit 5

# Use CM to check if there's a playbook rule

cm context "debugging API connection failures" --json

New to ACFS?

The Debugging Toolkit

RANO

CAUT

WA

CASS

Rate Limit Diagnosis

Network Debugging

Cost Investigation

Stuck Agent Detection

Learning from History

Ready to level up?

The Debugging Toolkit

RANO

CAUT

WA

CASS

Rate Limit Diagnosis

Network Debugging

Cost Investigation

Stuck Agent Detection

Learning from History