How to Detect Loops in Agent Executions with agent-trace-triage

The agent-trace-triage plugin detects loops in agent executions by scanning JSON/JSONL traces for three deterministic patterns—identical repeats, ping-pong alternations, and retry-without-progress failures—flagging issues when occurrences exceed a configurable threshold (default 3).

The agent-trace-triage plugin is a Claude Code utility from the anthropics/claude-plugins-community repository that analyzes execution traces produced by agentic frameworks such as LangGraph, CrewAI, or custom tool-calling loops. When you need to detect loops in agent executions, this tool provides deterministic, offline analysis of serialized trace data to identify stuck or runaway behavior without requiring network calls or external dependencies.

Three Core Loop Detection Patterns

The plugin implements specific algorithms in src/detectLoops.js to identify three classic failure modes in agent traces.

Identical Repeat Loops

The plugin flags identical repeat loops when the same tool call—including name, arguments, and resulting output—occurs consecutively beyond the threshold. The detection logic serializes each step in the trace and compares payloads for exact matches.

When detectLoops.js finds consecutive entries with identical serialized payloads repeating more than the default threshold of 3 times, it reports a repeat loop with the offending step indices.

Ping-Pong Loops

Ping-pong patterns emerge when two distinct calls alternate endlessly (e.g., A → B → A → B). The plugin builds a sliding window over the sequence of normalized calls and checks for a repeating 2-element cycle.

If the algorithm detects such a 2-step pattern repeating beyond the threshold, it flags a ping-pong loop and identifies the specific tool calls involved in the oscillation.

Retry-Without-Progress Loops

The retry-without-progress pattern occurs when an agent repeatedly retries a failed tool call without changing arguments or advancing state. The plugin examines traces for repeated failure statuses—errors, exceptions, or non-200 responses—where input arguments remain unchanged across attempts.

Once the retry count exceeds the threshold, the plugin flags this as a retry-without-progress loop, indicating the agent is stuck in a non-productive error recovery cycle.

Implementation Architecture

The detection system relies on a set of bundled Node.js scripts with zero external npm dependencies, enabling fully offline operation.

Key Source Files

File	Purpose
src/detectLoops.js	Core implementation housing the three loop-detection algorithms and sliding window logic.
src/traceParser.js	Normalizes incoming JSON/JSONL traces into a uniform step format for comparison.
src/cli.js	Command-line entry point that orchestrates parsing, detection, and report generation.
src/reportGenerator.md	Markdown templates for structured triage reports.

The traceParser.js module handles normalization of disparate trace formats, ensuring that tool calls, arguments, and status codes are comparable before detectLoops.js applies pattern-matching rules.

Usage Examples

You can invoke the plugin via command line or import it programmatically to detect loops in agent executions.

Command-Line Interface

Run the analyzer against any JSON or JSONL trace file:

npx agent-trace-triage trace.jsonl

The CLI performs three operations:

1. Parses the trace file using traceParser.js.
2. Executes detection algorithms from detectLoops.js.
3. Outputs a markdown triage report specifying loop type, offending steps, and remediation suggestions.

Programmatic Integration

Import the detection logic directly into Node.js applications:

import { detectLoops } from "agent-trace-triage";

const trace = await readFile("trace.jsonl", "utf8");
const results = detectLoops(trace);

if (results.loopDetected) {
  console.log("Loop type:", results.type);
  console.log("Offending steps:", results.steps);
}

The detectLoops() function returns an object containing the loop classification, step indices, and serialized payloads for forensic analysis.

Summary

• The plugin detects loops in agent executions through deterministic pattern matching on serialized trace data.
• Three specific patterns are monitored: identical repeats, ping-pong alternations, and retry-without-progress failures.
• Detection thresholds default to 3 occurrences but remain configurable.
• Core logic resides in src/detectLoops.js, with input normalization handled by src/traceParser.js.
• The tool operates entirely offline with no external npm dependencies, parsing JSON/JSONL traces locally via the CLI or programmatic API.

Frequently Asked Questions

What file formats does agent-trace-triage support?

The plugin accepts both JSON and JSONL (JSON Lines) formats. The traceParser.js module normalizes these inputs into a uniform step structure, enabling consistent analysis regardless of whether the trace is a single JSON array or a line-delimited stream of events.

Can I adjust the sensitivity of loop detection?

Yes. While the default threshold is 3 repetitions, you can configure this value when calling the detectLoops() function programmatically or via CLI arguments. Lowering the threshold catches subtle looping behavior earlier, while raising it reduces false positives in noisy traces.

Does the plugin require internet access to analyze traces?

No. The agent-trace-triage plugin contains no external npm dependencies and performs all analysis locally. The detection algorithms run deterministically against the supplied trace data without making network calls, ensuring privacy and operation in air-gapped environments.

How does the plugin distinguish between legitimate retries and retry-without-progress loops?

The algorithm examines both the status code (error, exception, or non-200 responses) and the input arguments. A retry-without-progress flag only triggers when the agent repeats the same failed call with identical arguments, indicating no state advancement. Successful retries or those with modified parameters are not flagged as loops.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}