Loop-Guard · Free local SDK

Stop an agent
repeating the same mistake.

Stop repeated tool calls and check reported spending in your own AI application.

Try a free example: watch an agent stop after three identical lookup attempts. No account or connection to your software needed.

Try the loop demo ↓

Interactive simulation

Choose an example, then run it to see when the guard stops the loop. This is a browser simulation; it does not protect your running agents.

🔴 1. Repeat a database lookup

The database does not respond. The agent tries the same lookup three times.

🟡 2. Alternate two failing actions

A website refuses access. The agent keeps switching connection and trying again.

🟣 3. Cross a $2 usage threshold

Reported model usage reaches $2.15 before the guard stops the next step.

Ready: run an example to see what stops and why.

Technical evidence: simulated tool calls

Simulated tool calls:

READY TO TRY

Choose an example and press "▶ Run simulation" to see the stopping point.

Reported spending / threshold $0.00 / $2.00

Example progress 0 / 3 steps

Simulated notification:

🚨 Slack / Telegram Alert Dispatcher

A notification preview appears here when the example stops. Nothing is sent.

Add it to your application

The simulation shows the idea. To protect your own tool calls, install the Python or TypeScript SDK and connect it to your runtime.

Complete Python/TypeScript integration example →

Budget checks use reported usage. A call already in progress can exceed your threshold; the $2 example reaches $2.15.

Installation, integration and budget details

How to Run & Configure Loop-Guard

Download the SDK, add it to your application, and test the thresholds with your own tool calls.

Install the SDK

First download the release packages, then run these commands in your downloads directory:

# Python
curl -fLO https://github.com/runlog-cc/loop-guard/releases/download/v0.3.0/runlog_loopguard-0.3.0-py3-none-any.whl
pip install ./runlog_loopguard-0.3.0-py3-none-any.whl

# TypeScript / Node.js
curl -fLO https://github.com/runlog-cc/loop-guard/releases/download/v0.3.0/runlog-loopguard-0.3.0.tgz
npm install ./runlog-loopguard-0.3.0.tgz

Configure the client (setup only)

This snippet only configures a synchronous, non-streaming OpenAI client. It does not execute or protect tools by itself. Add the explicit before/after lifecycle around each actual tool execution:

from openai import OpenAI
from loopguard import CircuitBreaker, TripPolicy, wrap_openai

# Set a 3-retry threshold and a reported-usage threshold.
guard = CircuitBreaker(
    policy=TripPolicy(
        max_consecutive_retries=3,
        max_cost_usd=2.00,
        fallback_mode="synthetic_response"
    )
)

client = wrap_openai(OpenAI(), guard)

Complete Python/TypeScript integration example →

Connect optional alerts

Get instant notifications if an agent is halted:

from loopguard import AlertDispatcher

alerts = AlertDispatcher(
    slack_webhook_url="https://hooks.slack.com/...",
    telegram_bot_token="123456:ABC...",
    telegram_chat_id="-100123456789"
)

guard.on_trip_callback = lambda cb, details: alerts.notify_trip(cb.to_dict(), details)

Budget thresholds can overshoot

The $2 demo stops after observing $2.15 of usage. This is an observed threshold, not a guaranteed hard cap: an in-flight call can exceed it. Pre-call reservations and provider-side output limits are separate protections. Slack and Telegram payloads here are simulated notification previews.

Complete the runtime step

Loop-Guard is the feedback stage of the free RunLog workflow: use what happens at runtime to refine your next prompt, baseline, and release check.

Loop-Guard 0.3.0 · Free source distribution

Retry/cycle detection, local session budget checks, and optional webhook alert integrations run inside your application. Configure and test thresholds for your workload. Budget checks depend on observed token usage and are not a guarantee against all upstream charges.

Download packages and checksums

Start the next design in Prompt Pricer · Read installation and integration documentation