agent-loop-guard

Agent Loop Guard

Agent Loop Guard is an Apache-2.0 local safety and observability toolkit for coding agents. It combines a loop guard, MCP permission firewall, session replay, deterministic benchmark lab, Docker-backed sandbox preview, interactive agent playground, IssuePilot, and ReproLab.

The default setup uses a local mock provider, so the demo works without an external API key.

Install

Install the current alpha from PyPI. The installed command is alg:

pipx install agent-loop-guard-runtime
# or
uv tool install agent-loop-guard-runtime

Run once without a permanent installation:

uvx --from agent-loop-guard-runtime alg doctor

For development from this checkout:

python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
alg setup
alg doctor
alg guard run

Open http://127.0.0.1:8787/playground, then run a deterministic scenario:

alg playground list
alg playground run exact-loop

Default local gateway key:

alg_demo_key

Proxy Endpoints

OpenAI-compatible:

POST /v1/responses
POST /v1/chat/completions
GET  /v1/models

Anthropic-compatible:

POST /v1/messages
POST /v1/messages/count_tokens

Connectivity probe:

HEAD /

Use Authorization: Bearer alg_demo_key or x-api-key: alg_demo_key.

alg setup creates a local YAML configuration and connection profiles for Codex, Claude Code, Cline, and OpenCode under .agent-loop-guard/profiles. Open http://127.0.0.1:8787/playground, then run a deterministic scenario without an external API key.

Modules

alg setup | doctor | status | open
alg guard run
alg playground list | run | open
alg issue import | plan | apply | export
alg repro create | run | status | diff | export
alg mcp run | serve | validate-policy | test-server
alg replay import | export
alg bench dataset validate | run | compare | regression-check
alg sandbox create | exec | diff | apply | discard | export

• Guard detects exact request, tool, error, and sequence loops with Shadow and Enforce modes.
• Playground visualizes deterministic requests, tool calls, policy decisions, loops, tokens, and Replay traces.
• IssuePilot converts a GitHub issue or local JSON fixture into an explicit technical plan and opt-in Git branch.
• ReproLab packages bug reports, environment metadata, sandbox logs, and diffs into portable local archives.
• MCP Firewall proxies stdio and Streamable HTTP, validates schemas, filters discovery, and applies YAML policies.
• Replay stores redacted traces, spans, events, costs, deterministic failure tags, and JSONL/OpenTelemetry exports.
• Benchmark Lab runs the bundled 30-task dataset through mock, HTTP, or CLI adapters and computes paired bootstrap confidence intervals.
• Sandbox Preview runs a copied workspace in a resource-limited Docker container and applies no changes before explicit approval.

Read the public documentation, Architecture, Threat Model, Benchmark Guide, and Sandbox Guide. A Russian overview is also available.

Agent Playground

alg playground list
alg playground run exact-loop
alg playground open

The HTTP API exposes GET /api/v1/playground/scenarios, POST /api/v1/playground/runs, and GET /api/v1/playground/runs/{id}. Scenario runs are stored as ordinary redacted Replay traces.

IssuePilot

alg issue import issue.json
alg issue plan ISSUE_ID
alg issue apply ISSUE_ID --repository .
alg issue export ISSUE_ID --output issue-plan.zip

Import and planning never modify GitHub or Git. apply is the explicit boundary that creates or switches the proposed branch.

ReproLab

alg repro create bug-report.md --source .
alg repro status REPRO_ID
alg repro run REPRO_ID
alg repro diff REPRO_ID
alg repro export REPRO_ID --output reproduction.zip

Package creation, inspection, and export work without Docker. Commands from a bug report run only through the Docker Sandbox workspace.

Guard Behavior

The guard implements:

• exact repeated request detection
• repeated tool call detection
• repeated upstream error detection
• repeated request sequence detection
• request and token limits
• project-level Shadow and Enforce modes
• manual session and agent pause/resume
• metadata-only logging by default
• JSON session export and aggregate CSV export
• trace runs, spans, events, replay UI, JSON export, and run comparison

Shadow Mode flags suspicious requests without blocking. Enforce Mode blocks requests when a blocking rule triggers.

MCP Firewall

Validate and run a stdio policy proxy:

alg mcp validate-policy app/mcp/presets/filesystem.yml
alg mcp run --policy app/mcp/presets/filesystem.yml -- your-mcp-server

For Streamable HTTP, configure a server under mcp.servers, run alg mcp serve, and connect to /mcp/{server_id}. Approval requests appear at /mcp. Raw arguments and secrets are redacted; audit records store hashes and policy metadata.

Session Replay

Every proxied model request now creates a replay trace automatically. Open:

http://127.0.0.1:8787/replay

The Replay view shows trace runs, model request spans, policy decision events, token totals, duration, source session links, JSON export, and a simple two-run comparison.

Replay ingest API:

POST /api/v1/traces
POST /api/v1/spans
POST /api/v1/events/batch
GET  /api/v1/runs
GET  /api/v1/runs/{trace_id}
GET  /api/v1/runs/{trace_id}/export?format=json|jsonl|otel
POST /api/v1/runs/import
POST /api/v1/runs/{trace_id}/pin
POST /api/v1/compare

CLI transfer:

alg replay export TRACE_ID --format jsonl --output trace.jsonl
alg replay import trace.jsonl

Benchmark Lab

alg bench dataset validate
alg bench run --adapter mock --candidate baseline --output baseline.jsonl
alg bench run --adapter mock --variant regressed --candidate candidate --output candidate.jsonl
alg bench regression-check baseline.jsonl candidate.jsonl

Parquet, DuckDB, and MLflow are optional:

pip install -e ".[bench]"

The regression command exits 0 for no regression, 1 for a statistically supported regression, and 2 when the result is inconclusive.

Sandbox Preview

Docker must be installed and running first. The original project is not mounted into the container; the sandbox uses a private copy.

alg sandbox create .
alg sandbox exec SANDBOX_ID -- pytest -q
alg sandbox diff SANDBOX_ID
alg sandbox apply SANDBOX_ID --path app/example.py
alg sandbox discard SANDBOX_ID

Network is disabled by default. This is a defense-in-depth development tool, not a certified security boundary; read the threat model before using it with untrusted code.

Minimal trace ingest example:

curl -X POST http://127.0.0.1:8787/api/v1/traces ^
  -H "Content-Type: application/json" ^
  -d "{\"trace_id\":\"demo_trace\",\"task_id\":\"demo\",\"spans\":[{\"name\":\"tool.call\",\"start_ns\":1,\"end_ns\":2000000}]}"

Agent Setup

Codex CLI:

model = "demo-model"
model_provider = "agent_loop_guard"

[model_providers.agent_loop_guard]
name = "Agent Loop Guard"
base_url = "http://127.0.0.1:8787/v1"
env_key = "ALG_GATEWAY_KEY"

Claude Code:

set ANTHROPIC_BASE_URL=http://127.0.0.1:8787
set ANTHROPIC_AUTH_TOKEN=alg_demo_key

OpenCode:

{
  "provider": {
    "alg": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Agent Loop Guard",
      "options": {
        "baseURL": "http://127.0.0.1:8787/v1",
        "apiKey": "{env:ALG_GATEWAY_KEY}"
      },
      "models": {
        "demo-model": {"name": "Guarded model"}
      }
    }
  },
  "model": "alg/demo-model"
}

Cline:

API Provider: OpenAI Compatible
Base URL: http://127.0.0.1:8787/v1
API Key: alg_demo_key
Model ID: demo-model

VS Code Extension

The VS Code extension starts the local guard daemon, shows health in the status bar, opens dashboard and replay views, and copies agent connection settings.

Install it from the VS Code Marketplace or from the command line:

code --install-extension RIMUMURUDEV.agent-loop-guard-vscode

Install the Python runtime first, then use Agent Loop Guard: Setup Current Workspace:

pipx install agent-loop-guard-runtime

Run the extension from source:

cd extensions/vscode
npm run check

Then open this repository in VS Code, press F5, and run Agent Loop Guard: Start Guard in the Extension Development Host.

Package and install a local .vsix:

cd extensions/vscode
npm run package
code --install-extension agent-loop-guard-vscode-0.2.0.vsix

If alg is installed globally, keep agentLoopGuard.startMode as cli. To run from this checkout instead, set:

{
  "agentLoopGuard.startMode": "source",
  "agentLoopGuard.pythonPath": ".venv\\Scripts\\python.exe",
  "agentLoopGuard.sourcePath": "C:\\path\\to\\agent-loop-guard"
}

After the guard is running, point agents at:

OpenAI base URL: http://127.0.0.1:8787/v1
Anthropic base URL: http://127.0.0.1:8787
API key: alg_demo_key

See extensions/vscode/README.md for all commands and settings.

Configuration

Create a config file:

alg init --path agent-loop-guard.yml

Run with it:

alg run --config agent-loop-guard.yml

Environment overrides include:

• ALG_HOST
• ALG_PORT
• ALG_STORAGE_URL
• ALG_MODE
• ALG_PROVIDER
• ALG_GATEWAY_KEY
• ALG_OPENAI_BASE_URL
• OPENAI_API_KEY
• ALG_ANTHROPIC_BASE_URL
• ANTHROPIC_API_KEY

Development

pip install -e ".[dev,docs]"
pytest -q
ruff check .
mkdocs build --strict

Run the documentation site locally:

mkdocs serve

The full contributor workflow is in CONTRIBUTING.md. Security assumptions and private reporting guidance are in SECURITY.md.

Docker:

docker compose up --build

Project Status

This repository is developed as an educational open-source project. Guard, MCP, Replay, and Benchmark are locally testable. Sandbox is a technical preview and its real Docker smoke-test runs only on Linux CI; it could not be executed on the current Windows machine because Docker is not installed. The Python runtime and VS Code extension are publicly available through PyPI and the VS Code Marketplace.

There is no telemetry, paid cloud, subscription, SLA, or closed feature set. Optional donations may be added later, but they do not influence architecture or priorities.

Limits

The toolkit only sees traffic routed through it. It does not provide enterprise IAM, distributed leases, legal audit guarantees, a kernel-level isolation guarantee, or hidden chain-of-thought capture. Full Content Logging is off by default and should not be enabled for sensitive data unless the data owner understands the risk.