Make any Python function or AI agent workflow crash-proof in 3 lines. Zero tokens wasted on SIGKILL.
Official Website & Demos • DCP-2.0 Leaderboard • GitHub Action v2 • Quickstart • Cookbooks • Architecture
LetItLoop eliminates the central failure mode of autonomous AI coding agents and long-horizon Python scripts: the lack of deterministic verification, uncatchable mid-task SIGKILL crashes, and destructive whole-file rewrites.
graph TD
subgraph "The Tripartite Ecosystem"
LL["<b>letitloop</b> (Core Engine)<br/>Deterministic WAL plumbing, AST node splicer & FastSandbox"]
LLA["<b>letitloop-action</b> (Marketplace v2)<br/>Drop-in CI gate signing proof bundles on Pull Requests"]
ADB["<b>agent-durability-bench</b> (DCP-2.0)<br/>Open benchmark measuring agent recovery under SIGKILL faults"]
end
LL -.->|"bridges to"| ADB
LL -.->|"scaffolds"| LLA
letitloop(Official Website): The core engine providing single-file Write-Ahead Logging (WAL) state journals, source-span AST node splicing (0% comment loss), in-memory Zero-Copy fast sandboxing, and deterministic verification gates.letitloop-action(Marketplace): Zero-dependency GitHub Action for CI that validates AI pull requests, enforces strict AST signatures, and posts machine-verifiable proof bundles directly to PR comments.agent-durability-bench(Leaderboard): An open benchmark suite implementing Durability Conformance Protocol 2.0 (DCP-2.0) with zero-API synthetic simulation to measure how well agents recover from uncatchable SIGKILL crashes.
Make any Python function or AI agent workflow crash-proof in 3 lines:
from letitloop import durable, step, atomic_marker
@durable(goal_id="customer_sync")
def sync_workflow():
# If this process crashes or gets SIGKILLed midway,
# completed steps are skipped on resume. Zero duplicate tokens wasted.
user = step("fetch_user", fetch_crm_record, user_id=123)
summary = step("summarize", call_claude, user)
# Protect external API mutations against duplicate execution
with atomic_marker("slack_notification") as should_execute:
if should_execute:
step("notify", send_slack, summary)
return summary
if __name__ == "__main__":
sync_workflow()⚡ Async Support: For asynchronous pipelines, use
@durable_asyncandawait async_step(...)with fullasyncio.gather()isolation.
# Install core durability kernel
pip install letitloop
# Or install with dev & conformance tooling
pip install "letitloop[dev]"# Run a task under strict WAL supervisor containment
lil run --task auth-refactor --strict
# Run self-benchmarking crash injection and verify WAL recovery
lil bench --self --script examples/workflow.py
# Check supervisor status, active locks, and WAL journal entries
lil status
# Export CRA-compliant CycloneDX Software Bill of Materials (SBOM)
lil sbom --format cyclonedx --output sbom.jsonLetItLoop uses Deterministic Simulation Testing (DST) inspired by the distributed systems verification methodologies of FoundationDB, TigerBeetle, Jepsen, and Antithesis:
- OS SIGKILL Chaos Injection: Tested against 500+ physical OS signal injections (
kill -9, SIGKILL 137, spot-instance preemptions, and OOM aborts) across all execution boundaries. - 250 / 250 DST Fault Matrix (100% Passed): Systematic fault injection across the 4 durability sentinels (
SENTINEL_PROMPT,SENTINEL_EXEC,SENTINEL_WRITE,SENTINEL_VERIFY). While raw agent loops fail 100% of the time and naive in-memory graphs fail 87.6% of the time, LetItLoop achieves 100.0% zero-state-loss recovery. - Torn WAL & Bitrot Fuzzing: 5,000+ property-based fuzzing permutations (via Hypothesis) inject random mid-frame disk writes, torn tails, and single-bit CRC32 corruptions—verifying automatic fail-safe prefix repair without state loss.
- Multi-OS CI Matrix: 1,457 unit tests + 250 DST fault matrices running 100% green across Ubuntu (3.11/3.12), macOS (3.11/3.12), and Windows (3.11/3.12).
- Source-Span AST Node Splicer: Replaces targeted functions and class methods with surgical precision. 0% Comment Loss: Guarantees module docstrings, file comments, licensing headers, and class indentation are never stripped or altered.
- In-Memory Fast Sandbox: Zero-Copy
sys.modulesevaluation and Windows Job Object containment that verifies code hypotheses in-memory before writing anything to disk. - Fault-Tolerant WAL Supervisor Loop: State journal with WAL (Write-Ahead Logging), crash recovery, atomic Win32/POSIX file locking, and bounded 3-strike retries with strategy mutation.
- Cognitive Feasibility Gate & Multi-Source Research: Deliberates whether a refactor is safe to perform autonomously or requires background research across arXiv, GitHub, and DuckDuckGo.
- Human-in-the-Loop Proposal Ledger: Automatically stages deferred, high-risk architectural proposals as structured markdown artifacts (
PROP-*.md) for human review rather than executing unverified mutations. - Zero-Trust Verification Engine: Deterministic acceptance check kinds (AST syntax parsers, command exit-code assertions, regex matchers, file validators, size bounds, and undeclared output detectors).
- 12 Pluggable Worker Adapters: Native interfaces for Claude Code, OpenAI Codex, Google Antigravity (
agy), OpenCode, Hermes Agent, Cline, Aider, Docker Sandboxes, Local LLMs (Ollama/vLLM), Omniroute gateways, local scripts, and direct LLMs. - Native Model Context Protocol (MCP) Server: 8 stdio JSON-RPC tools connecting directly with Claude Code, Cursor, Antigravity, and Hermes Agent:
claude mcp add letitloop -- python -m orchestrator.mcp_server
- Cross-Platform Process Orphan Guard: Windows Job Objects (
JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE) and POSIX session process-group containment ensuring complete cleanup of child/grandchild processes.
LetItLoop integrates natively with major AI agent frameworks. Explore runnable self-contained examples in examples/cookbooks/:
| Framework | Cookbook | Description |
|---|---|---|
| LangGraph | Financial Analyst Cookbook | 4-step yfinance + StateGraph equity analysis surviving simulated SIGKILL |
| DSPy | Prompt Optimizer Cookbook | Async BootstrapFewShot / Teleprompter tuning with zero lost progress |
| CrewAI | Durable Tools Example | Multi-agent tool execution with step-level resumption and zero duplicate side-effects |
| LlamaIndex | Durable Workflows Example | Event-driven @step pipeline with crash durability and sub-millisecond fast-forward |
| OpenAI Swarm | Durable Handoff Example | Multi-agent context handoff with WAL v2 serialization |
Run any cookbook directly in demo/mock mode:
python examples/cookbooks/langgraph_financial_analyst.py --demo
python examples/cookbooks/dspy_durable_optimize.py --demo| Worker Adapter | Identifier | Description | Tier |
|---|---|---|---|
| Google Antigravity CLI | antigravity-cli |
Invokes the official agy agent runner safely |
Tier-1 (Core) |
| Claude Code CLI | claude-code |
Autonomous task execution via Claude Code CLI | Tier-1 (Core) |
| OpenAI Codex CLI | codex |
Autonomous task execution via OpenAI Codex CLI | Tier-1 (Core) |
| Mock Worker | mock |
Deterministic simulation worker for CI and offline tests | Tier-1 (Core) |
| OpenCode CLI | opencode |
Autonomous execution via OpenCode agent CLI | Tier-2 (Contrib) |
| Hermes Agent CLI | hermes |
Autonomous execution via Nous Research Hermes agent CLI | Tier-2 (Contrib) |
| Cline CLI | cline |
Headless execution via Cline autonomous coding runner | Tier-2 (Contrib) |
| Aider Pair Programmer | aider |
Pair programming execution via Aider CLI | Tier-2 (Contrib) |
| Docker Sandbox Worker | docker |
Isolated execution inside container runtime with workspace scoping | Tier-2 (Contrib) |
| Local LLM Tool Caller | local-tool |
Local tool-calling model adapter for offline Ollama/vLLM loops | Tier-2 (Contrib) |
| Omniroute Gateway | omniroute |
Multi-model fallback routing through local/remote gateways | Tier-2 (Contrib) |
| Script Worker | script |
Executes local shell/Python automation scripts with env isolation | Tier-2 (Contrib) |
| Direct LLM APIs | direct |
In-process calls to Gemini, OpenAI, Anthropic, DeepSeek, or Ollama | Tier-2 (Contrib) |
Drop letitloop-action@v2 into your CI/CD pipeline to block non-deterministic agent changes, enforce AST signatures, and verify proof bundles:
name: LetItLoop Proof-Carrying CI Gate
on: [pull_request]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Run LetItLoop Verification Gate
uses: sdageltc/letitloop-action@v2
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
strict-ast: 'true'Following the Michael Nygard ADR convention, all core design invariants and architectural decisions are codified:
| ADR | Focus | Status |
|---|---|---|
| ADR-0001 | Write-Ahead Logging (WAL) & Zero-State Recovery | accepted |
| ADR-0002 | Deterministic AST, Regex & Exit-Code Verification Gates | accepted |
| ADR-0003 | Zero-API-Key Headless Agent CLI Wrapper Failovers | accepted |
| ADR-0004 | Format-Aware Acceptance Check & Markdown Injection | accepted |
Click to expand Enterprise Compliance, CRA Invariants & Security Specifications
- Deterministic Verification: All agent-generated patches require proof bundles signed with HMAC-SHA256.
- Software Bill of Materials (SBOM): CycloneDX and SPDX format export via
lil sbom --format cyclonedx. - Zero-Trust Redaction: Automatic masking of PATs, OAuth tokens, AWS credentials, and PEM private keys before logging.
- Process Orphan Containment: Windows Job Objects (
JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE) and POSIX session groups ensure orphan processes are reaped on exit.
Distributed under the MIT License. Copyright (c) 2026 sdageltc. See LICENSE for details.