darkzloop 0.7.0

Reliable. Autonomous. Model-Agnostic. Turn any LLM into a disciplined software engineer.

♾️ Darkzloop

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

Darkzloop is a terminal-based agent runner that turns any LLM into a rigorous software engineer. Unlike flaky chat agents, Darkzloop uses a Finite State Machine, Circuit Breakers, and Manifest Protocols 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

---

⚡ Quick Start

1. Install

pip install darkzloop

2. Run

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:

• 🔍 Detect your project type (Rust/Python/Node/Go)
• 🛡️ Create a safety backup branch
• 🔄 Plan, Execute, and Test the fix using your project's own test suite

Optional: Verify Setup

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

---

🛡️ Why Darkzloop?

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
Manifest Protocol	Agent edits files blindly	Read-Before-Write: Writes blocked unless file is in context
Circuit Breakers	Agent tries the same wrong fix 10×	Task Limits: Hard stop after 3 failed attempts per task
Tiered Gates	Agent breaks the build	Quality Control: Tests must pass before loop completes
Semantic Expansion	"Fix billing" misses src/invoice.rs	Synonyms: Auto-expands intent to find relevant files
Git Safety	Agent overwrites uncommitted work	Backup Branches: Auto-creates restore points before execution

---

🧠 Supported Backends

Darkzloop works with any tool that accepts text via stdin.

Backend	Best For	Setup
Claude CLI	Complex refactors, high reasoning	darkzloop config native claude
Ollama	Privacy, offline, free	darkzloop config native ollama
GitHub Copilot	Quick fixes with Enterprise license	darkzloop config native gh-copilot
llm CLI	Universal adapter (50+ providers)	darkzloop config native llm
Direct API	Full control, streaming	darkzloop config api anthropic

---

🛠️ Usage Examples

Quick Fix

darkzloop "Login button not responding on mobile"

With Backend Override

darkzloop "Add rate limiting" --backend ollama

Skip Safety Prompts (CI/CD)

darkzloop "Fix lint errors" --unattended

Check Environment

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 ./...

---

📦 Architecture

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

┌─────────────────────────────────────────────────────────────┐
│                    DARKZLOOP CONTROL PLANE                   │
│                                                              │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐               │
│  │   FSM    │───▶│ Manifest │───▶│  Gates   │               │
│  │  Engine  │    │ Protocol │    │ (Tests)  │               │
│  └──────────┘    └──────────┘    └──────────┘               │
│        │              │               │                      │
│        ▼              ▼               ▼                      │
│  ┌─────────────────────────────────────────┐                │
│  │         Semantic Expansion Layer         │                │
│  │   (Synonyms, Learning Glossary, Search)  │                │
│  └─────────────────────────────────────────┘                │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │   Executor Layer    │
              │  (Model-Agnostic)   │
              └──────────┬──────────┘
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
   ┌─────────┐     ┌──────────┐     ┌─────────┐
   │ Claude  │     │  Ollama  │     │   API   │
   │  CLI    │     │ (Local)  │     │ (SDK)   │
   └─────────┘     └──────────┘     └─────────┘

Finite State Machine

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

                    ┌─────────────────────────────────────┐
                    │                                     │
                    ▼                                     │
┌──────┐    ┌───────────┐    ┌───────────┐    ┌─────────┐│
│ IDLE │───▶│ PLANNING  │───▶│ EXECUTING │───▶│ TESTING ││
└──────┘    └───────────┘    └───────────┘    └────┬────┘│
                                                   │     │
                              ┌─────────────┐      │     │
                              │             │      │     │
                    ┌─────────┤ REMEDIATING │◀─────┘     │
                    │         │             │ (tests     │
                    │         └─────────────┘  failed)   │
                    │               │                    │
                    │               │ (fix applied)      │
                    │               └────────────────────┘
                    │
                    │ (max retries exceeded)
                    ▼
              ┌─────────┐         ┌──────┐
              │ BLOCKED │         │ DONE │◀── (tests passed)
              └─────────┘         └──────┘

State	Description	Exit Condition
IDLE	Waiting for task	Plan approved
PLANNING	Agent generates plan	Plan validated
EXECUTING	Agent works on current task	Task complete
TESTING	Running tiered gates	Pass → DONE, Fail → REMEDIATING
REMEDIATING	Self-healing after test failure (max 3 retries per task)	Fix applied → TESTING
BLOCKED	Circuit breaker tripped	Human intervention required
DONE	All tasks complete, all gates passed	—

Key Components

• FSM Engine: 7-state machine with strict transitions—no skipping states
• Manifest Protocol: Tracks every file read/write, enforces read-before-write, user must approve sensitive file additions
• Circuit Breakers: Max iterations (100), consecutive failures (3), per-task retries (3)
• Semantic Layer: Expands search terms using local synonym matching + learning glossary (no external API calls, no data leaves your machine)
• Executor Interface: Pluggable backends via stdin/stdout protocol

The Manifest Protocol (Read-Before-Write)

┌─────────────────────────────────────────────────────────────┐
│                      MANIFEST RULES                          │
├─────────────────────────────────────────────────────────────┤
│  ✓ Agent wants to READ src/api/users.rs                     │
│    → Allowed (adds to manifest automatically)               │
│                                                              │
│  ✗ Agent wants to WRITE src/api/users.rs (not in manifest)  │
│    → BLOCKED: "Must read file before modifying"             │
│                                                              │
│  ⚠ Agent wants to READ config/secrets.json                  │
│    → PROMPT: "Add sensitive file to manifest? [y/N]"        │
│                                                              │
│  ✓ Agent wants to WRITE src/api/users.rs (in manifest)      │
│    → Allowed (file was previously read)                     │
└─────────────────────────────────────────────────────────────┘

This prevents the #1 agent failure mode: blindly overwriting files it hasn't seen.

Semantic Expansion

When you say darkzloop fix "billing issue", the semantic layer expands your intent:

Input:  "billing"
        ↓
Synonyms: ["invoice", "payment", "charge", "subscription", "price"]
        ↓
Learned: ["stripe", "checkout"] (from project glossary)
        ↓
Search:  Finds src/billing.rs, src/invoice.rs, src/stripe/webhook.rs

Implementation: Local dictionary + project-specific learning glossary stored in .darkzloop/glossary.json. No embeddings, no external calls—fast and private.

---

🔧 Configuration

Zero config by default. Darkzloop auto-detects everything.

Optional overrides via environment:

DARKZLOOP_BACKEND=ollama     # Use Ollama instead of Claude
DARKZLOOP_MAX_ITER=5         # Limit iterations

---

📊 Commands

Command	Description
darkzloop "task"	Run a fix or feature (main usage)
darkzloop "task" --backend ollama	Override LLM backend
darkzloop "task" --unattended	Skip safety prompts (for CI)
darkzloop doctor	Verify environment and configuration

---

🚨 Safety Features

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. Dry Run Mode: --dry-run shows what would happen without executing
4. Attended Mode: Requires approval at each major step
5. Read-Before-Write: Cannot modify files not explicitly loaded into context
6. Sensitive File Prompts: Asks permission before reading config/secrets

---

🎯 Philosophy

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

Darkzloop is based on the Ralph Loop methodology:

1. Spec: Define what you want (the "Pin")
2. Plan: Break it into tasks with dependencies (DAG)
3. Execute: Let the agent work within strict boundaries
4. Verify: Run tests before accepting any change
5. Learn: Build project-specific vocabulary over time

The agent is powerful. The system keeps it honest.

---

🤝 Contributing

See CONTRIBUTING.md for guidelines.

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

---

📄 License

MIT © 2025

---

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