LoopRelay

Wireshark for agent loops — record, replay, and debug every iteration step-by-step.

The Problem

Debugging an AI agent loop today means:

1. Open a massive JSONL file (10-50MB)
2. Search through raw JSON for the iteration where things went wrong
3. Reconstruct what the agent saw, did, and decided at each step
4. Compare two runs by reading through both logs manually
5. Paste truncated JSON into Slack to share a failure

There's no Chrome DevTools equivalent for agent loops. You're reading logs and guessing.

What LoopRelay Does

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

Install

# 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

Quick Start

# 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

TUI Playback

┌─ 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 │
└─────────────────────────────────────────────────────────────────────┘

Failure Classification

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

Competitive Landscape

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

Part of the loop-eng Ecosystem

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

License

MIT