The LetItLoop Tripartite Ecosystem

LetItLoop solves the central failure mode of autonomous AI coding agents: 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 and FastSandbox"]
        LLA["<b>letitloop-action</b> (Marketplace)<br/>Drop-in CI gate signing proof bundles on Pull Requests"]
        ADB["<b>agent-durability-bench</b> (DCP-1.0)<br/>Open benchmark measuring agent recovery under SIGKILL faults"]
    end

    LL -.->|"bridges to"| ADB
    LL -.->|"scaffolds"| LLA

1. letitloop: The core engine providing sub-2ms Write-Ahead Logging (WAL) state journals, source-span AST node splicing (0% comment loss), in-memory Zero-Copy fast sandboxing, and deterministic verification gates.
2. letitloop-action: Standalone GitHub Action for CI that validates AI pull requests, enforces strict AST signatures, and posts machine-verifiable proof bundles directly to PR comments.
3. agent-durability-bench: An open benchmark suite implementing Durability Challenge Protocol 1.0 (DCP-1.0) with zero-API synthetic simulation to measure how well agents recover from uncatchable SIGKILL crashes.

Key Capabilities

• 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.modules evaluation 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 & Client: 8 stdio JSON-RPC tools connecting directly with Claude Code, OpenAI Codex, Cursor, Google Antigravity, and Hermes Agent.
• Cross-Platform Process Orphan Guard: Windows Job Objects (win32job) and POSIX session process-group containment ensuring complete cleanup of child/grandchild processes.
• Prometheus Observability & Signed Webhooks: Native Prometheus metrics exporter, lifecycle event bus, SSE streaming, and HMAC-SHA256 signed webhook dispatcher.

Quickstart

1. Installation

# Install letitloop core engine
pip install letitloop

# Or install with all development and worker dependencies
pip install "letitloop[dev]"

2. Basic CLI Usage

# Propose a contract DAG from a natural language objective
lil propose "Build a rate limiter middleware with unit tests" --run

# Bridge to the agent durability benchmark
lil bench --steps 5

# Scaffold a production GitHub Action PR verification workflow
lil action --init

# Inspect live supervisor status, WAL journal, and active checkpoints
lil status

# Run deterministic reconciliation audit across workspace files
lil reconcile <goal_id>

Supported Worker Adapters & Gateways

Model Context Protocol (MCP) Integration

LetItLoop runs natively as an MCP server providing 8 JSON-RPC tools to AI agent runners:

{
  "mcpServers": {
    "letitloop": {
      "command": "letitloop-mcp",
      "env": {
        "WORKER_MODEL": "gemini:gemini-3.7-flash",
        "QC_MODEL": "gemini:gemini-3.1-pro"
      }
    }
  }
}

Add to Claude Code

claude mcp add letitloop -- python -m orchestrator.mcp_server

Recipes & Cookbooks

The recipes/ cookbook provides end-to-end, schema-validated walkthroughs:

Validate all embedded example contracts anytime with pytest tests/test_recipes.py -q.

Living Architecture Decision Records (ADRs)

Following the Michael Nygard ADR convention, all core design invariants and architectural decisions are codified:

Security & Sandboxing Architecture

letitloop operates under a zero-trust execution model:

• Redaction Firewall: Automatic masking of PATs, OAuth keys, AWS credentials, GCP tokens, and PEM private keys.
• Environment Scrubbing: Sensitive parent environment variables are stripped prior to worker execution.
• Scope Checking: Userland filesystem snapshot diffing (scope.py) enforcing directory bounds and declared output paths.
• Process Isolation: Process tree containment with Windows Job Objects (JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE) and POSIX session leadership.

License

Distributed under the MIT License. See LICENSE for more details.