let it loop (LIL) is an autonomous macro-task orchestration and verification control loop for AI coding agents. It provides a durable, production-grade execution backbone featuring automated DAG contract planning, crash-resilient supervisor execution (Write-Ahead Logging), deterministic multi-phase verification, multi-lens quality reviews, and universal Model Context Protocol (MCP) support.
- Autonomous DAG Planning: Decomposes natural language objectives into cryptographically scoped, strongly-typed JSON contract dependency graphs with cycle detection.
- Fault-Tolerant Supervisor Loop: State journal with WAL (Write-Ahead Logging), crash recovery, Win32/POSIX atomic file-locking, and bounded 3-strike retries with strategy mutation.
- Zero-Trust Verification Engine: 8 distinct deterministic acceptance check kinds (AST syntax parsers, command exit-code assertions, regex matchers, file validators, size bounds, and undeclared output detectors).
- Multi-Lens Quality Plane: Multi-perspective evaluation with 5 specialized lenses (Code Correctness, Security Hardening, Documentation Fidelity, Test Completeness, Adversarial Architecture Audit) and formal arbitration.
- Native Model Context Protocol (MCP) Server: 8 stdio JSON-RPC tools connecting directly with Claude Code, Cursor, Google Antigravity, Hermes Agent, OpenCode, Cline, and Windsurf.
- 9 Pluggable Worker Adapters: Native execution interfaces for Claude Code, Google Antigravity (
agy), OpenCode, Hermes Agent, Cline, Aider, Omniroute gateways, local scripts, and direct LLMs. - Zero-Subscription Independence: Seamlessly run 100% locally via Ollama/vLLM, multi-model gateways (Omniroute, OpenRouter, Groq), or commercial frontier APIs.
- Interactive Terminal Dashboard: Zero-dependency live ASCII DAG status matrix, execution progress bars, and event telemetry (
lil dashboard). - Turnkey Containerization: Production multi-stage Docker build and Docker Compose orchestration.
Unlike conversational agent loops that rely on open-ended text streaming and optimistic assumptions, letitloop operates like an Operating System process scheduler: every task requires a cryptographic contract, empirical acceptance proof, and bounded retry governance.
| Architectural Feature | letitloop (LIL) | OpenHands | SWE-agent | AutoGPT / AgentGPT | MetaGPT / ChatDev |
|---|---|---|---|---|---|
| Orchestration Model | Typed DAG Contracts | Container Terminal Chat | Single-Task Benchmark Agent | Open-Ended While-Loop | Multi-Role Chat Simulation |
| Deterministic Verifier | 8 Machine-Verified Checks (AST, Cmd Exit Codes, Regex, Render, Scope) | Eyeball / Agent Judgement | Unit Test Execution Only | None (LLM Self-Assessment) | Role-Play Text Review |
| Crash Recovery & Resume | Write-Ahead Log (WAL) Journal | Manual Session Replay | No (Ephemeral Run) | None (Lost State) | None |
| Retry & Failure Policy | Bounded 3-Strike with Strategy Mutation & Impossibility Proof | Infinite Loop / Timeout | Fixed Retries / Prompt Dump | Infinite Hallucination Loop | Reprompting Loop |
| Sandbox Scope Enforcement | Strict allow/deny & Undeclared Output Detection |
Docker Container Isolation | Bash Environment Isolation | None (Unrestricted Host) | None |
| Quality Plane & Lenses | 5 Specialized Lenses + Senior Arbitration & QC Overrule | Single Review Step | None | None | Simulated Peer Chat |
| AI Ecosystem & Skill Support | Universal Skill & MCP across 7 Platforms (Claude Code, Antigravity, Hermes, Cursor, OpenCode, Cline, Windsurf) | Standalone Web UI / Docker | Standalone CLI | Standalone CLI / Web | Standalone Framework |
| Zero-Subscription Local Use | Native Ollama, vLLM, LM Studio & Omniroute Support | Local LLMs supported via LiteLLM | Local LLMs supported | Local LLMs (Ollama) | Local LLMs supported |
letitloop can be used both as a standalone Python CLI / MCP engine and as a universal Agent Skill inside your favorite coding agent (Claude Code, Cursor, Google Antigravity, Hermes Agent, OpenCode, Cline, Windsurf):
python skill/install_skill.py --all(Or specify --claude, --cursor, --antigravity, --hermes, --opencode, --cline, --windsurf)
- Full Engine Mode (
pip install -e .+ Skill / MCP):- Full Capabilities: Host agents invoke the
lilCLI orletitloop-mcptools directly. - Machine-Enforced Proof: Real AST syntax parsers (Python, TypeScript, JS, Go, Rust), true command exit-code assertions (
exit_code == 0), OS process-tree timeout killing, and atomic Write-Ahead Log (WAL) journal locks.
- Full Capabilities: Host agents invoke the
- Skill-Only / Zero-Install Mode (
skill/SKILL.mdprompt only):- Self-Governed Protocol: If you copy
SKILL.mdinto your agent environment without installing Python, the agent follows the structured DAG contract lifecycle, 3-strike escalation rules, and multi-lens quality gates directly inside chat. - Note: Machine-verified AST parsing, rogue file detection, and OS-level crash recovery require the Python package runtime.
- Self-Governed Protocol: If you copy
# Clone the repository
git clone https://github.com/sdageltc/letitloop.git
cd letitloop
# Install package in editable mode
pip install -e .
# Verify CLI installation
lil --helpConfigure your environment variables in .env (see .env.example):
# Core API Keys
export GEMINI_API_KEY="your-gemini-key"
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export DEEPSEEK_API_KEY="your-deepseek-key"
# Model Routing Defaults
export WORKER_MODEL="gemini:gemini-3.6-flash"
export QC_MODEL="gemini:gemini-3.1-pro"
export PLANNER_MODEL="gemini:gemini-3.6-flash"
# Optional Gateways (Omniroute, OpenRouter, Groq, Ollama)
export OMNIROUTE_BASE_URL="http://localhost:8000/v1"letitloop includes a built-in MCP server (letitloop-mcp) exposing 8 autonomous management tools for AI assistants.
{
"mcpServers": {
"letitloop": {
"command": "letitloop-mcp",
"env": {
"WORKER_MODEL": "gemini:gemini-3.6-flash",
"QC_MODEL": "gemini:gemini-3.1-pro"
}
}
}
}claude mcp add letitloop -- python -m orchestrator.mcp_serverOr in ~/.claude.json:
{
"mcpServers": {
"letitloop": {
"command": "python",
"args": ["-m", "orchestrator.mcp_server"]
}
}
}For detailed integration instructions, see docs/MCP_GUIDE.md.
# Propose a contract DAG from a natural language prompt and execute it
lil propose "Build a user authentication module with JWT validation and unit tests" --run
# View real-time terminal dashboard
lil dashboard
# Run deterministic reconciliation audit across workspace files
lil reconcile <goal_id> ┌───────────────────────────┐
│ Natural Language Goal │
└─────────────┬─────────────┘
▼
┌───────────────────────────┐
│ LLM DAG Planner │
└─────────────┬─────────────┘
▼
┌───────────────────────────┐
│ Contract Dependency Graph │
└─────────────┬─────────────┘
▼
┌─────────────────────────────────┐
│ Supervisor Loop │
│ - Preflight & Sandbox Scoping │
│ - Pluggable Worker Execution │
│ - Deterministic Verification │
│ - Multi-Lens QC Review │
└─────────────┬───────────────────┘
▼
┌─────────────────────────────────┐
│ Cryptographic Evidence Ledger │
│ & Reconciled Workspace Outputs │
└─────────────────────────────────┘
| Worker Adapter | Identifier | Description |
|---|---|---|
| Google Antigravity CLI | antigravity-cli |
Invokes the official agy subagent tool safely |
| Claude Code CLI | claude-code |
Autonomous task execution via the Claude Code CLI |
| Omniroute Gateway | omniroute |
Multi-model fallback routing through local/remote gateways |
| Script Worker | script |
Executes local shell/Python automation scripts with env isolation |
| Direct LLM APIs | direct |
In-process calls to Gemini, OpenAI, Anthropic, DeepSeek, or Ollama |
| Mock Worker | mock |
Deterministic simulation worker for CI and offline integration tests |
# Run all unit tests (362 tests across 65 modules)
python -m pytest tests -q --ignore=tests/test_integration.py --ignore=tests/test_benchmarks.py
# Run end-to-end integration tests
python -m pytest tests/test_integration.py -v
# Fast in-process verification runner
python fast_test_runner.pyletitloop is built with a zero-trust security architecture:
- Redaction Firewall: Automatic masking of PATs, OAuth keys, AWS credentials, GCP tokens, and PEM private keys.
- Sandbox Scoping: Deny-by-default path scoping preventing directory traversal or unauthorized file modifications.
- Safe Subprocess Spawning: Isolated execution environments with explicit permission boundaries.
Distributed under the MIT License. See LICENSE for more details.