Wireshark for agent loops — record, replay, and debug every iteration step-by-step.
Debugging an AI agent loop today means:
- Open a massive JSONL file (10-50MB)
- Search through raw JSON for the iteration where things went wrong
- Reconstruct what the agent saw, did, and decided at each step
- Compare two runs by reading through both logs manually
- Paste truncated JSON into Slack to share a failure
There's no Chrome DevTools equivalent for agent loops. You're reading logs and guessing.
| Feature | Description |
|---|---|
| Step-through playback | Navigate iterations like a debugger (←/→) |
| Side-by-side comparison | Compare two runs to see what diverged |
| Failure classification | Auto-categorize why a loop failed (7 categories) |
| Fork-from-checkpoint | Re-run from any iteration with different parameters |
| HTML export | Shareable single-file replay for blog posts and bug reports |
| Multi-agent support | LTF, Claude Code, Codex CLI, Copilot CLI |
# Homebrew
brew install loop-eng/tap/looprelay
# Go
go install github.com/loop-eng/looprelay/cmd/looprelay@latest
# Binary
curl -sSfL https://github.com/loop-eng/looprelay/releases/latest/download/looprelay_$(uname -s)_$(uname -m).tar.gz | tar xz# Replay a trace file
looprelay play trace.ltf.jsonl
# Classify why a loop failed
looprelay classify trace.ltf.jsonl
# Compare two runs
looprelay diff run-a.jsonl run-b.jsonl
# Export as shareable HTML
looprelay export trace.ltf.jsonl
# Fork from iteration 3 with a different model
looprelay fork trace.ltf.jsonl --at 3 --model claude-haiku-4-5
# List recent sessions
looprelay ls --today┌─ LoopRelay: session 5e9bb524 ──────────────────────────────────────┐
│ │
│ Iteration 3 of 7 │ Phase: verify │ Cost so far: $1.23 │
│ ─────────────────────────────────────────────────────────────────── │
│ │
│ ┌─ Agent Action ──────────────────┐ ┌─ Verification Result ──────┐ │
│ │ Model: claude-sonnet-4-6 │ │ Command: npm test │ │
│ │ Action: edit_file │ │ Status: FAIL ✗ │ │
│ │ Target: src/auth.ts │ │ │ │
│ │ │ │ 2 tests failed: │ │
│ │ + import { verify } from 'jwt' │ │ ✗ auth.test.ts:42 │ │
│ │ - import { decode } from 'jwt' │ │ Expected: 401 │ │
│ │ + const token = verify(...) │ │ Received: 200 │ │
│ │ - const token = decode(...) │ │ │ │
│ │ │ │ │ │
│ │ Tokens: 1,200 in / 450 out │ │ │ │
│ │ Cost: $0.024 │ │ │ │
│ └─────────────────────────────────┘ └─────────────────────────────┘ │
│ │
│ ┌─ Context Window ────────────────────────────────────────────────┐ │
│ │ Fill: ████████████░░░░░░░░░░░░░░░░░░ 45% (90K/200K) │ │
│ │ Compactions: 0 │ Cache hit: 67% │ Efficiency: 37% │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ [←] prev [→] next [g] go to [d] diff [t] timeline [e] export│
│ [/] search [?] help [q] quit │
└─────────────────────────────────────────────────────────────────────┘
LoopRelay auto-classifies loop failures:
| Category | Signal |
|---|---|
| Spin | Same tool call 3+ times |
| Budget exhausted | Cost exceeds limit |
| Verifier too strict | Correct edits but verification always fails |
| Context overflow | Compaction > 3×, fill > 90% |
| Tool error | Unrecovered tool call error |
| Drift | Goal vs. final changes diverged |
| False completion | Claimed success, tests actually fail |
| Feature | looprelay | claude-replay | Mantra | Copilot Explorer |
|---|---|---|---|---|
| TUI playback | ✓ | — | — | — |
| Step-through | ✓ | — | ✓ | Partial |
| Side-by-side | ✓ | — | — | — |
| Classification | ✓ | — | — | — |
| Fork-from-checkpoint | ✓ | — | — | — |
| HTML export | ✓ | ✓ | — | — |
| LTF support | ✓ | — | — | — |
| Multi-agent | ✓ | ✓ | ✓ | Copilot only |
LTF Spec → LoopGuard → LoopCtl → Kit → Loop-Bench → LoopRelay
- LTF — Loop Trace Format standard
- LoopGuard — Circuit breaker daemon
- LoopCtl — Live terminal dashboard
- Kit — Loop scaffolding CLI
- Loop-Bench — Standardized benchmarks
MIT