mcpField
L
loop-circuit-breaker

loop-circuit-breaker

github.com/archieindianAgent workflows7348 installsUpdated 26w ago
Repository

About loop-circuit-breaker

An automatic retry-loop detection skill for OpenClaw that monitors tool-call failures within each session. When an identical call signature fails repeatedly, it stops retries, records the issue, and asks the user how to proceed.

Key features

  1. 01Tracks tool-call history per session
  2. 02Detects repeated failures by call signature
  3. 03Classifies transient and deterministic errors
  4. 04Stops retries and records state when triggered
  5. 05Provides a command to adjust the threshold

Use cases

  1. 01Prevent repeated tool calls with invalid arguments
  2. 02Limit retries for timeouts or rate limits
  3. 03Stop loops before repeated failures exhaust context
  4. 04Present errors and options to fix, skip, or abort

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/archieindian/openclaw-superpowers --skill loop-circuit-breaker

After installing, type/loop-circuit-breakerin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

check.py
example-state.yaml
STATE_SCHEMA.yaml

Details

From the project README

loop-circuit-breaker

OpenClaw retries all errors identically — whether transient (rate limit, timeout) or deterministic (missing parameter, type error, invalid path). This skill tracks tool call history per session, identifies repeated identical failures, and halts the loop before it exhausts the context window and API budget.

Difference from agent-self-recovery

agent-self-recovery is a manual, reactive recovery protocol — the user or agent invokes it after noticing the agent is stuck.

loop-circuit-breaker is automatic and proactive — it triggers on the 2nd identical failure, before the user even notices.

Detection algorithm

On every tool call result, the agent should check:

  1. Was this tool call a failure (error, exception, or empty result)?
  2. Normalise the call signature: (tool_name, sorted_args_hash, error_type)
  3. Look up this signature in the session's call history in state
  4. If the same signature has failed N times (default: 2), trigger the circuit breaker

N=2 rationale: One retry is reasonable for transient errors. Two identical failures with identical args strongly indicates a deterministic error that retrying cannot resolve.

Error classification

Error typeClassificationMax retries
Rate limit (429)Transient3
Timeout / networkTransient3
Missing required parameterDeterministic1
Type error / validationDeterministic1
File not foundDeterministic1
Permission deniedDeterministic1
Unknown errorUnknown2

When the circuit trips

  1. Stop retrying immediately — do not emit the same call again
  2. Diagnose the root cause — read the error message carefully
  3. Write LOOP_DETECTED to state with: tool name, args, error, fail count, first/last timestamp
  4. Surface to user: "I've detected a retry loop on <tool>(<args>). The error is: <error>. I've stopped retrying. How would you like me to proceed?"
  5. Offer options: fix the args, skip this step, or abort the task

Session scope

Loop detection is per-session. State resets at the start of each new session. Call history older than 2 hours is pruned from state automatically.

Tuning

To adjust the deterministic retry threshold:

python3 check.py --set-threshold 3   # Allow 3 failures before tripping

Comments

Markdown supported