Agent Loop Guardian Pro

The free version makes your agent notice it's looping. The Pro version detects loops from OUTSIDE the agent, enforces token budgets, exports metrics to Grafana, and auto-remediates with a decision tree.

Free vs Pro

The free guardian gives the agent in-context instincts to notice its own loops. Pro enforces from outside: a standalone watchdog CLI that reads live transcripts, per-project configurable thresholds, Prometheus metrics for Grafana, hard token/cost budgets with a kill switch, and an auto-remediation decision tree. Free asks the agent to self-police — Pro polices the agent.

Upgrade Path

Free for interactive sessions; Pro for overnight batch runs, CI agents, or any workload where a loop burns real money while you sleep.

The Problem

The free Agent Loop Guardian teaches your agent to recognize when it's repeating itself and break out. But the agent is the one with the problem — asking it to self-diagnose a loop is like asking a drunk driver to pull over. You need external detection (a watchdog that watches the transcript), enforceable budgets (hard token/cost caps that actually terminate runaway tasks), observability (metrics you can alert on), and a mechanical remediation process (not "hope the agent figures it out"). The Pro version turns loop protection from an in-context suggestion into a production-grade system.

What You Get

• Standalone watchdog CLI — scans live agent transcripts and command logs for loop signatures from outside the agent, catching loops even when the agent's own reasoning misses them.
• Configurable thresholds — every detection rule is tunable per project via YAML config (edit count, tool call count, outcome similarity tolerance, backoff caps), instead of hard-coded counts.
• Fuzzy similarity detection — catches near-identical repeats (same command with changed counter or flag) via token-based Jaccard similarity, not just exact hashes.
• Prometheus metrics export — loop_detections_total, loop_tokens_wasted_estimate, loop_duration_seconds, budget_remaining_tokens in standard text format for Grafana dashboards.
• Budget enforcement — hard token and cost caps per task with a cost-aware kill switch that terminates work before a runaway loop exceeds its allowance.
• Auto-remediation playbook — structured decision tree (checkpoint restore → cache clear → dependency rebuild → handoff) that the agent or orchestrator runs mechanically.

Why This Beats Prompting It Yourself

The free version asks the agent to notice it's looping. The agent has to be not-looping in order to notice it's looping — a contradiction. This Pro version runs an external watchdog that reads the transcript independently, so loops are caught even when the agent's reasoning is compromised. The budget enforcement is mechanical (hard kill switch), not advisory ("please stop"). The Prometheus metrics let you alert on loop rates across agent fleets, not just individual sessions.

Example Session

You: "Run the watchdog on our overnight batch migration. It's processing 500 repos and I want to catch loops before they burn through our API budget."

Agent:

python3 scripts/loop_watchdog.py watch --log /var/log/batch-migration.log \
  --config config/loop-guardian.yaml --budget-tokens 500000 --budget-cost $50

WATCHDOG REPORT — batch-migration.log
Duration: 3h 12m | Repos processed: 387/500 | Loops detected: 2

LOOP #1 — Edit oscillation (repo: acme-api)
  Detected at: 2026-09-21 02:14:33
  Pattern: src/config.ts lines 45-62 edited 7 times in 4 minutes
  Similarity: 0.89 (fuzzy — line numbers shift each iteration)
  Action: Checkpoint restored to pre-loop state, task reassigned to fresh session
  Tokens saved: ~12,400 | Duration: 4m 12s

LOOP #2 — Tool call repetition (repo: widget-factory)
  Detected at: 2026-09-21 03:47:11
  Pattern: git diff → npm test → npm test → npm test (3 identical calls)
  Similarity: 0.95
  Action: Cache cleared, dependency rebuild triggered, task resumed
  Tokens saved: ~3,200 | Duration: 1m 45s

BUDGET STATUS
  Tokens used: 387,200 / 500,000 (77.4%)
  Cost used: $31.80 / $50.00 (63.6%)
  Projected completion: repo 471/500 (29 remaining)
  Budget risk: LOW — sufficient headroom

PROMETHEUS METRICS EXPORTED
  loop_detections_total 2
  loop_tokens_wasted_estimate 15600
  loop_duration_seconds 357
  budget_remaining_tokens 112800
  budget_remaining_cost 18.20

Use Cases

• Monitoring overnight batch agent jobs (migrations, bulk refactors, CI pipelines with agent steps).
• Fleet-level observability: dashboard showing loop rates, token waste, and budget consumption across all agent sessions.
• CI/CD integration: watchdog as a step that fails the build if agent loops are detected.
• Cost control for API-billed agent workflows with hard budget caps.
• Post-incident analysis: review loop history to write prevention rules for future tasks.

Known Limitations

The watchdog CLI reads transcript/log files — it requires structured logging from the agent (not all agents output parseable transcripts). Fuzzy similarity detection uses Jaccard similarity with a configurable threshold; very short commands may produce false positives. Prometheus metrics are in text format; Prometheus server setup is required for dashboards. Budget enforcement terminates the task abruptly — ensure critical writes are checkpointed before starting budgeted work.