bounded-loops

Two things ship in this package: a standalone bounded loop engine and a graph engine that composes loops into DAGs. Each is a complete, independently useful program.

pip install bounded-loops
git clone https://github.com/qualixar/bounded-loops && cd bounded-loops
bl run loops/bug-fix-red-green --yes    # a real planted bug, a real pytest gate, no API key

68 loop packages ship in loops/; 64 need no API key. The catalog is in the repository, not the wheel — bl run takes a path and writes its ledger beside the loop.

What this is

A bounded loop is a single agent task driven to a verified finish. A worker attempts the task; a separate object — the gate — decides pass or fail; the engine retries up to a declared bound. The gate is never the worker. The worker's own claim of "done" is recorded as metadata and ignored by the control path. State is an append-only hash-chained event log. Run one with bl run <loop>.

A graph (bl graph) is a DAG whose nodes are agent tasks. Use it when you need fan-out, conditional branching, join, human approval checkpoints, or an irreversible publish step. Each node has its own gate, and the same invariant holds whether you run one task or fifty.

Loops are not only graph substrate. Someone with one gated task gets full value from a loop in ten minutes, never touching the graph engine.

Loop or graph?

Shipped loops that stand on their own: bug-fix-red-green, citation-existence-check, cors-not-wildcard, dependency-pinning, dead-import-clean, contract-clause-extraction. Full index: catalog/README.md.

Quickstart: a loop

No API key. The runner is a stub; the gate is real pytest.

pip install bounded-loops
git clone https://github.com/qualixar/bounded-loops
cd bounded-loops
bl run loops/bug-fix-red-green --yes

Output:

[bounded-loops] About to run loop 'bug-fix-red-green':
  runner : stub
  gate   : pytest -q
✓ [DONE] gate-passed (laps: 1)  ledger: loops/bug-fix-red-green/.ledger.jsonl
Gate verified: the independent acceptance gate passed after 1 lap.

Now see a loop that needs multiple laps:

bl run loops/convergence-demo --yes

✓ [DONE] gate-passed (laps: 3)  ledger: loops/convergence-demo/.ledger.jsonl

The worker's agent_claimed_done field is recorded in the ledger and never read by the control path. Only the gate decides when the loop exits.

Quickstart: a graph

No agent CLI or credentials needed. Runs in-process, no OS sandbox — the banner says "DEMONSTRATION" and the run directory is marked accordingly.

bl graph demo --out ./demo-run
bl graph status --run ./demo-run

The next one is different: it enforces real OS isolation (macOS Seatbelt or Linux bubblewrap, no Docker), still with no credential.

bl graph run --execute --out ./sandbox-demo

A built-in probe node runs inside the sandbox, attempts a network connection and an out-of-workspace write, and an independent gate passes only if the OS denied both.

To run a real agent graph (needs your already-logged-in claude, codex, grok, muse, or agy CLI):

bl graph run --execute manifest.yaml \
  --connections connections.json \
  --inputs inputs.json \
  --out ./my-run

Full instructions for creating manifest.yaml, connections.json, and inputs.json are in docs/graph-quickstart.md.

Bounded loops in depth

The engine loop

On every lap:

1. The runner works inside a quarantined scratch copy of seed/.
2. The gate evaluates the workspace independently.
3. The engine records the verdict, token use, and timing.
4. A passing gate yields DONE; exhausted bounds yield HALT; a crash yields ERROR.

The gate is a separate object from the runner. The controller checks worker is gate (Python identity) and refuses to run if the check trips. This forbids one object playing both roles — it does not enforce that the gate's logic is truly independent of the worker's output. A wrapped worker (GateWrapper(worker)) that rubber-stamps its input passes the identity check. The guarantee: no code path branches on agent_claimed_done; only verdict.passed can produce a DONE outcome.

The 68-loop catalog

64 loops are keyless (stub runner + real mechanical gate — offline, deterministic, no API key). 4 require a framework package (langgraph, crewai, agent-framework, or google-adk). Gate kinds: 44 command, 10 jsonschema, 9 pytest, 3 composite, 1 osv, 1 checkov. No loop uses "an LLM decides" as its gate.

Domains: software, security, finance, legal, healthcare, retail, operations, enterprise/ERP, testing, content, research, business.

Worth reading first:

• bug-fix-red-green — the smallest pytest loop. Ships wreck.sh, which runs the same prompt ungated: the agent claims GREEN, pytest fails.
• citation-existence-check — the checker and reporter are in forbid:, so the agent cannot edit what the gate reads.
• convergence-demo — two failures, a passing third lap, and a deliberate max-iteration trip.

Create your own loop

bl new --list                        # show available templates
bl new pytest-basic my-loop          # scaffold from a template
bl lint my-loop                      # validate manifest and bounds
bl run my-loop --yes                 # run it

Full how-to with worked examples: docs/WRITING-A-LOOP.md.

Runners

Built-in gates

command, pytest, jsonschema, composite, plus typed adapters for osv, checkov, gitleaks, semgrep, trivy, promptfoo, great_expectations, and axe. Typed gates parse structured output and fail closed on malformed reports. Run bl gates to check local tool availability.

Graph engine in depth

bl graph compiles a YAML manifest into an execution plan, validates every connection binding at compile time, and runs each node inside a native OS sandbox (macOS Seatbelt or Linux bubblewrap — no Docker). Every run writes an append-only, hash-chained event log. The read-only Arena renders that log without re-executing anything.

Node kinds

loop, tool, router, join, approval, audit, research_source, research_claim, subgraph, publish.

What bl graph run --execute runs today: nodes with an admitted local_cli or https connector binding, plus kind: loop, join, approval and publish. Every other kind is still refused by a fail-closed preflight.

Graph commands

bl graph lint manifest.yaml                              # validate the DAG
bl graph plan manifest.yaml --connections connections.json    # compile to plan
bl graph run --execute manifest.yaml \
    --connections connections.json --out ./run           # run; pauses at approval (exit 3)
bl graph approve --run ./run --node <id> \
    --decision approved                                  # record decision, resume
bl graph console --run ./run                             # browser click-to-approve
bl graph arena --run ./run                               # render read-only Arena HTML
bl graph status --run ./run                              # text projection of the event log
bl graph init                                            # configure egress posture

Connector modes

• Local-CLI — runs your already-logged-in agent CLI (claude, codex, grok, muse, agy) as a subprocess. The engine never reads, stores, or logs credentials.
• BYOK / HTTPS — routes a node to a model API via a no-secret egress broker that issues single-use, time-bound leases and denies SSRF and DNS-rebind (private, loopback, link-local, CGNAT and reserved ranges).

What the graph gate does and does not check

StructuralAcceptanceGate re-reads the node's promoted artifact from the store, separately from the worker, and passes if it is non-empty and UTF-8-decodable. That is structural acceptance — a well-formed reply exists. It is not a semantic review. The cross-model audit engine (--audit-plan) is the overlay for that.

Honest capability matrix

Full detail: docs/graph-capabilities.md. Runnable walkthrough: docs/graph-quickstart.md.

Nine enforced bounds and a kill switch

BOUNDED_LOOPS_KILL is checked before every lap. Gate commands are tokenized and run without a shell. Runner environments use an environment-variable allowlist. Details and threat boundaries: docs/NINE-BOUNDS.md and SECURITY.md.

Architecture

Hexagonal (ports-and-adapters). The domain rule — the gate decides, not the agent — lives in one file (bounded_loops/application/run_loop.py) and holds regardless of which runner, gate, or storage backend a loop uses. The graph engine reuses the same ports per node. bounded_loops/composition.py is the composition root.

Full design: docs/ARCHITECTURE.md.

Codex, Claude Code, MCP, and editors

pip install "bounded-loops[mcp]"
git clone https://github.com/qualixar/bounded-loops
cd bounded-loops
codex plugin marketplace add .
codex plugin add bounded-loops@bounded-loops

The bounded-loops-mcp server exposes loop tools — run, lint, list, show, gates, audit, run-history — over the composition root. The graph MCP shim (graph_status / graph_resume / graph_approve) mounts onto a deployment's own server via a runtime facade; subject identity binds to the MCP session, never an LLM tool argument.

Provider plugins are a boundary, not a sandbox. A plugin is arbitrary code in this process and can monkey-patch the worker. The narrower guarantee worth stating exactly: the engine's own resolution path will not hand a plugin's values to a subprocess, and its checks cannot be defeated by mutating something they read.

Claude Code and Antigravity packages, the isolated install test, and local-development commands: plugins/README.md.

Known limitations

• A kind: loop node whose loop_package digest resolves on this host runs; one that does not is refused at preflight.
• bl graph run --execute pauses at approval nodes (exit code 3, AWAITING_APPROVAL) and resumes via bl graph approve. Sandboxed arbitrary-tool nodes are a later phase.
• The ALLOWLIST egress cage is a network-only restriction on macOS Seatbelt. A caged subprocess still has full filesystem access.
• The Arena's LOCAL/UNVERIFIED notice is accurate: local runs are not verified against a hosted receipt server.
• content-fact-gate and OSV scans require network access; the quickstart is offline.
• Framework example glue uses deterministic edits and reports changed: true; production glue should compute a before/after diff.
• Python 3.11+ required. The npm package is a thin Python launcher, not a second engine.

Credits

bounded-loops did not invent loop engineering. Addy Osmani named and described the practice in Loop Engineering. The project also builds on Andrej Karpathy's evaluability framing, Boris Cherny's agent-loop practice, Peter Steinberger's prompting-loop discussion, Matthew Berman's Loop Library, and runnable verifier-loop projects such as proof-loop, repo-task-proof-loop, and agentops. This repository's contribution is the executable harness: enforced bounds, independent gates, receipts, a graph engine, and a cross-domain source catalog.

Contributing, citation, and security

See CONTRIBUTING.md. A contributed loop needs a real failing seed, a passing fix, a testable done-condition, and bl lint --contrib compliance. Never use "an LLM decides" as the gate.

Research citation metadata is in CITATION.cff. Report gate bypasses or sandbox escapes privately through SECURITY.md.

Apache-2.0. Copyright © 2026 Varun Pratap Bhardwaj / Qualixar, an independent AI Reliability Engineering research initiative.