Reliable. Autonomous. Model-Agnostic.
Stop hand-carrying cargo. Operate the locomotive.

Darkzloop is a terminal-based agent runner that transforms any Large Language Model into a disciplined, autonomous software engineer. Instead of building a smarter agent, Darkzloop builds a more disciplined one—wrapping model outputs in a rigorous control system that prevents hallucinations, drift, and infinite loops.

Core Architecture:

• 🔄 7-State FSM — Enforced transitions through Plan → Execute → Observe → Critique → Checkpoint
• 🧠 Context Grounding — Agent receives Mermaid diagrams of its own control flow every iteration
• ⚡ Circuit Breakers — Hard stop after 3 consecutive failures; no spiral of bad fixes
• 🔍 Auto-Detection — Scans for Rust/Python/Node/Go and runs appropriate quality gates
• 🔐 BYOA (Bring Your Own Auth) — Uses your existing CLI tools; no API keys required

Darkzloop is a terminal-based agent runner that turns any LLM into a rigorous software engineer. Built on the Ralph Wiggum Loop methodology, it uses a Finite State Machine, Mermaid context diagrams, and Circuit Breakers to prevent hallucinations and infinite loops.

🔥 The Killer Feature: Bring Your Own Auth (BYOA)
Darkzloop doesn't need your API keys. It pipes context directly to the tools you're already logged into:

Claude CLI • GitHub Copilot • Ollama • llm CLI • Aider

pip install darkzloop

Navigate to your project and describe the task. Darkzloop auto-detects your stack.

darkzloop "Fix the retry logic in the webhook handler"

That's it. Darkzloop will:

• � Darkz Loop through Plan → Execute → Observe → Critique → Checkpoint
• 🔍 Auto-detect your project type (Rust/Python/Node/Go)
• 🛡️ Create a safety backup branch
• ⚡ Show animated spinner while working

🟡 [EXECUTING] iter=1 fails=0
⠴ 🔄 Darkz Looping...

darkzloop doctor
# ✓ Backend: claude
# ✓ Project: Python
#   Tier 1: ['ruff check .']
#   Tier 2: ['pytest -x']

Process multiple files concurrently with the new batch command:

# Process entire folder with 4 parallel workers
darkzloop batch ./src --workers 4 --task "Fix security vulnerabilities"

⚡ Batch Processing: 51 files with 4 workers
Processing... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%

Results:
  ✓ Success: 51
  ✗ Failed: 0

Most AI agents are just "loops in a while(true) block." They drift, hallucinate, and overwrite good code. Darkzloop is different:

Darkzloop works with any tool that accepts text via stdin.

darkzloop "Login button not responding on mobile"

darkzloop "Add rate limiting" --backend ollama

darkzloop "Fix lint errors" --unattended --no-gates

darkzloop batch ./vulnerable-code --workers 8 --task "Fix SQL injection"

darkzloop doctor

Auto-detected quality gates by stack:

• Rust: cargo check → cargo test
• Python: ruff check . → pytest -x
• Node: npm run lint → npm test
• Go: go build ./... → go test ./...

Darkzloop implements the Ralph Wiggum Loop methodology with industrial-grade hardening:

┌─────────────────────────────────────────────────────────────┐
│                    DARKZLOOP CONTROL PLANE                   │
│                                                              │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐               │
│  │   FSM    │───▶│  Mermaid │───▶│  Gates   │               │
│  │  Engine  │    │ Context  │    │ (Tests)  │               │
│  └──────────┘    └──────────┘    └──────────┘               │
│        │              │               │                      │
│        ▼              ▼               ▼                      │
│  ┌─────────────────────────────────────────┐                │
│  │           Stdin Prompt Delivery          │                │
│  │   (Bypasses shell escaping entirely)     │                │
│  └─────────────────────────────────────────┘                │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │   Executor Layer    │
              │  (Model-Agnostic)   │
              └──────────┬──────────┘
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
   ┌─────────┐     ┌──────────┐     ┌─────────┐
   │ Claude  │     │  Ollama  │     │   API   │
   │  CLI    │     │ (Local)  │     │ (SDK)   │
   └─────────┘     └──────────┘     └─────────┘

The FSM enforces strict state transitions—no "hallucinated" jumps:

graph LR
    INIT --> PLAN
    PLAN --> EXECUTE
    EXECUTE --> OBSERVE
    OBSERVE --> CRITIQUE
    CRITIQUE --> CHECKPOINT
    CRITIQUE --> TASK_FAILURE
    TASK_FAILURE --> PLAN
    CHECKPOINT --> COMPLETE
    TASK_FAILURE --> BLOCKED

Each iteration, the agent receives structured context:

# DARKZLOOP AGENT CONTEXT
FSM: EXECUTE | iter=2 | fails=1 | max_fails=3

## FSM State Diagram
graph LR; PLAN-->EXECUTE; EXECUTE-->OBSERVE...

## Current Task
Fix the SQL injection vulnerability

## Instructions
You are inside a Ralph Wiggum loop. Your changes persist between iterations.

Darkzloop is designed to never lose your work:

1. Git Clean Check: Warns before running with uncommitted changes
2. Backup Branches: Creates darkzloop-backup-YYYYMMDD-HHMMSS before execution
3. Circuit Breakers: Max 3 consecutive failures before stopping
4. Attended Mode: Requires approval at each major step
5. Stdin Delivery: Complex prompts with special characters work perfectly

"The goal is not to build a smarter agent. It's to build a more disciplined one."

Darkzloop is based on the Ralph Wiggum Loop methodology:

1. Plan: Receive task + FSM context + Mermaid diagram
2. Execute: Let the agent work within strict boundaries
3. Observe: Run quality gates (linters, tests)
4. Critique: Evaluate results, decide next action
5. Checkpoint: Accept changes or retry

The agent is powerful. The system keeps it honest.

git clone https://github.com/darkzOGx/darkzloop
cd darkzloop
pip install -e ".[dev]"
pytest

Generate a nightmare test suite:

cd vulnerable-api
python generate_nightmare_suite.py
# Creates 50 files with various vulnerabilities

darkzloop batch nightmare_suite --workers 4
# Processes all files in parallel

MIT © 2025

Stop debugging your debugger. Start shipping.
pip install darkzloop && darkzloop "your bug here"