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 darkzloopNavigate 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| Option | Description |
|---|---|
--workers N |
Number of parallel Ralph workers (default: 4) |
--task "..." |
Task to apply to each file |
--backend X |
Override LLM backend |
Most AI agents are just "loops in a while(true) block." They drift, hallucinate, and overwrite good code. Darkzloop is different:
| Feature | The Problem | The Darkzloop Solution |
|---|---|---|
| Ralph Loop | Agent runs aimlessly | FSM-controlled Plan→Execute→Observe→Critique→Checkpoint |
| Circuit Breakers | Agent tries the same wrong fix 10× | Task Limits: Hard stop after 3 failed attempts |
| Tiered Gates | Agent breaks the build | Quality Control: Tests must pass before loop completes |
| Stdin Delivery | Shell escaping mangles prompts | Direct stdin: Complex prompts with Mermaid diagrams work perfectly |
| Git Safety | Agent overwrites uncommitted work | Backup Branches: Auto-creates restore points |
Darkzloop works with any tool that accepts text via stdin.
| Backend | Best For | Auto-Detected |
|---|---|---|
| Claude CLI | Complex refactors, high reasoning | ✓ |
| Ollama | Privacy, offline, free | ✓ |
| GitHub Copilot | Quick fixes with Enterprise license | ✓ |
| llm CLI | Universal adapter (50+ providers) | ✓ |
darkzloop "Login button not responding on mobile"darkzloop "Add rate limiting" --backend ollamadarkzloop "Fix lint errors" --unattended --no-gatesdarkzloop batch ./vulnerable-code --workers 8 --task "Fix SQL injection"darkzloop doctorAuto-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
| State | Description | Exit Condition |
|---|---|---|
| PLAN | Agent receives FSM context + Mermaid diagram | Plan ready |
| EXECUTE | Agent works on task (🔄 Darkz Looping...) | Changes made |
| OBSERVE | Run quality gates | Pass/Fail |
| CRITIQUE | Evaluate results | Success → CHECKPOINT |
| CHECKPOINT | Task complete | All done → COMPLETE |
| TASK_FAILURE | Max 3 retries, then → BLOCKED | Fix applied → retry |
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.| Command | Description |
|---|---|
darkzloop "task" |
Run a fix or feature (main usage) |
darkzloop batch path/ |
Process files in parallel |
darkzloop batch path/ --workers 8 |
Control parallelism |
darkzloop "task" --backend ollama |
Override LLM backend |
darkzloop "task" --unattended |
Skip safety prompts (for CI) |
darkzloop "task" --no-gates |
Skip quality gates (for testing) |
darkzloop doctor |
Verify environment and configuration |
Darkzloop is designed to never lose your work:
- Git Clean Check: Warns before running with uncommitted changes
- Backup Branches: Creates
darkzloop-backup-YYYYMMDD-HHMMSSbefore execution - Circuit Breakers: Max 3 consecutive failures before stopping
- Attended Mode: Requires approval at each major step
- 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:
- Plan: Receive task + FSM context + Mermaid diagram
- Execute: Let the agent work within strict boundaries
- Observe: Run quality gates (linters, tests)
- Critique: Evaluate results, decide next action
- 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]"
pytestGenerate 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 parallelMIT © 2025
Stop debugging your debugger. Start shipping.
pip install darkzloop && darkzloop "your bug here"