agent-loop-detector

Detect and break repetitive loops in tool-using AI agents — with a corrective nudge, not just a crash.

The problem

Give an LLM a set of tools and a long-running task and it will, sooner or later, get stuck. Three failure modes dominate:

Identical repeated calls

It calls the same tool with the same arguments over and over, expecting a different answer.

Cyclic tool-call patterns

It oscillates between the same tools every turn — the "submit proposal batch #265… forever" death spiral.

Idle status-check loops

It keeps calling git_status, check_credits, list_goals and never actually does anything.

agent-loop-detector catches all three and returns a plain-English reason you inject back into the model so it corrects course — escalating cyclic loops from a warning to a hard enforcement block.

Install

npm i github:Princeu3/agent-loop-detector

npm package coming soon.

Quick start

import { LoopDetector } from "agent-loop-detector";

const detector = new LoopDetector({
  maxIdenticalCalls: 3,
  maxIdleOnlyTurns: 3,
  windowSize: 10,
});

// per tool call
const check = detector.recordToolCall(name, argsJson);
if (check.blocked) return { role: "tool", content: check.reason };

// at end of each turn
const turn = detector.endTurn();
if (turn.reason) inject(turn.reason);

// new task
detector.reset();

How it catches loops

recordToolCall(name, args) — blocks after maxIdenticalCalls identical calls in a row.
endTurn() — warns on the 3rd repeat of a tool-call pattern, then hard-blocks if ignored.
endTurn() — nudges after maxIdleOnlyTurns turns that used only idle/status tools (configurable via idleOnlyTools).
reset() — clears all state between tasks.

Pairs well with

Drop this in as the loop-safety layer alongside react-agent-loop (the agent loop itself) and agent-policy-engine (spend / action policy).

Attribution

Extracted, refactored, and decoupled by Prince Upadhyay (@Princeu3) from the MIT-licensed Conway-Research/automaton project. Zero runtime dependencies.