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

> Learn how agent-trace-triage detects agent execution loops using pattern analysis. Discover how to identify and resolve repetitive failures for smoother agent performance.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-12

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/src/detectLoops.js) | Core implementation housing the three loop-detection algorithms and sliding window logic. |
| [`src/traceParser.js`](https://github.com/anthropics/claude-plugins-community/blob/main/src/traceParser.js) | Normalizes incoming JSON/JSONL traces into a uniform step format for comparison. |
| [`src/cli.js`](https://github.com/anthropics/claude-plugins-community/blob/main/src/cli.js) | Command-line entry point that orchestrates parsing, detection, and report generation. |
| [`src/reportGenerator.md`](https://github.com/anthropics/claude-plugins-community/blob/main/src/reportGenerator.md) | Markdown templates for structured triage reports. |

The [`traceParser.js`](https://github.com/anthropics/claude-plugins-community/blob/main/traceParser.js) module handles normalization of disparate trace formats, ensuring that tool calls, arguments, and status codes are comparable before [`detectLoops.js`](https://github.com/anthropics/claude-plugins-community/blob/main/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:

```bash
npx agent-trace-triage trace.jsonl

```

The CLI performs three operations:
1. Parses the trace file using [`traceParser.js`](https://github.com/anthropics/claude-plugins-community/blob/main/traceParser.js).
2. Executes detection algorithms from [`detectLoops.js`](https://github.com/anthropics/claude-plugins-community/blob/main/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:

```javascript
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`](https://github.com/anthropics/claude-plugins-community/blob/main/src/detectLoops.js), with input normalization handled by [`src/traceParser.js`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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.