slavedriver

Multi-agent orchestration that actually ships code.

One command. Multiple AI agents. Parallel execution. Real results.

npx slavedriver "build a REST API with auth, users, and tests"

slavedriver spawns a team of AI agents that discover your codebase, plan the work, execute tasks in parallel waves, and verify the results — all with a lazygit-style TUI you can watch and control.

The Problem

Multi-agent orchestration is fragmented. Every framework picks one pattern and builds a universe around it. GSD has great wave execution but no TUI. OpenClaw has the best autonomous heartbeat but requires a full server. CrewAI has nice agent roles but locks you into their ecosystem. Ralph Wiggum's iterative loop is genius but it's just a bash script.

slavedriver cherry-picks the best patterns from all of them into a single npx command.

Key Features

• Wave Execution — Tasks organized in dependency-aware waves that run in parallel (from GSD)
• Full TUI — lazygit/k9s-style terminal UI with task board, agent output, and live controls
• Ralph Loop — Iterative self-improvement mode: run, check, fix, repeat (from Ralph Wiggum)
• Heartbeat Daemon — Autonomous scheduled agent that checks on your project (from OpenClaw)
• Fresh Context Per Task — Every agent spawns clean. No context rot. Ever (from GSD)
• Git Worktree Isolation — Each agent works in its own branch/directory. No conflicts (from Claude Code Teams)
• File-Based State — No databases. .slavedriver/ is the state. Human-readable. Git-friendly
• Zero Production Dependencies — Built-in Node.js APIs only
• Model-Agnostic — Claude Code CLI, Anthropic API, OpenAI, Ollama — bring your own backend
• Safety First — Budget limits, iteration caps, path exclusions, human approval gates

Quick Start

# Run with a goal (discover -> plan -> execute -> verify)
npx slavedriver "add user authentication with JWT"

# Launch the interactive TUI
npx slavedriver

# Just generate a plan
npx slavedriver plan "refactor the database layer"

# Execute an existing plan
npx slavedriver run

# Run in Ralph Wiggum loop mode
npx slavedriver run --ralph

# Start the autonomous heartbeat daemon
npx slavedriver heartbeat --daemon

TUI

┌══════════════════════════════════════════════════════════════════┐
│  SLAVEDRIVER v0.1.0  │  Project: my-api  │  Phase: EXECUTING    │
│  Wave 2/4  │  Tasks: 3/12 done  │  Agents: 3 active  │  $0.42  │
├═══════════════════════╤══════════════════════════════════════════┤
│                       │                                          │
│  TASK BOARD           │  AGENT OUTPUT                            │
│                       │                                          │
│  Wave 1 [████] DONE   │  > planner (opus)                        │
│    [x] T1: Setup DB   │  Analyzing codebase structure...         │
│    [x] T2: Init proj  │  Found 47 files across 12 modules.      │
│                       │  Generating task dependency graph...     │
│  Wave 2 [██  ] 1/3    │                                          │
│    [x] T3: Auth       │  ─────────────────────────────────────   │
│    [>] T4: User CRUD  │  > executor-1 (sonnet)                   │
│    [>] T5: API routes │  Writing src/routes/users.ts...          │
│                       │  Created 4 endpoints: GET, POST,         │
│  Wave 3 [    ] 0/2    │  PUT, DELETE. Running tsc... OK          │
│    [ ] T6: Tests      │                                          │
│    [ ] T7: Integrate  │  ─────────────────────────────────────   │
│                       │  > executor-2 (sonnet)                   │
│  Wave 4 [    ] 0/1    │  Implementing auth middleware...         │
│    [ ] T8: Deploy     │  JWT generation complete.                │
│                       │                                          │
├═══════════════════════╧══════════════════════════════════════════┤
│  [q]uit [p]ause [r]esume [a]bort [l]ogs [t]asks [Tab]focus [?] │
│  > _                                                             │
└══════════════════════════════════════════════════════════════════┘

Architecture Overview

CLI / TUI
    │
    ├── Orchestrator (state machine: DISCOVER → PLAN → EXECUTE → VERIFY)
    │       │
    │       ├── Task Graph (DAG with wave-based parallel execution)
    │       ├── Safety Engine (budgets, caps, exclusions)
    │       ├── Heartbeat Daemon (autonomous scheduled runs)
    │       └── Ralph Loop (iterative self-improvement mode)
    │
    ├── Session Manager (tmux backend + git worktree isolation)
    │       │
    │       └── Agent 1..N (each in isolated worktree + fresh context)
    │
    ├── Agent Runtime (model-agnostic abstraction)
    │       │
    │       └── Backends: Claude Code CLI | Anthropic API | OpenAI | Ollama
    │
    └── State Store (file-based, .slavedriver/ directory)
            │
            ├── STATE.md, PLAN.md, CONTEXT.md
            ├── tasks.jsonl (append-only event log)
            └── config.json

See .planning/ARCHITECTURE.md for the full system design.

Project Structure

.slavedriver/           # Per-project state (created by `slavedriver init`)
  ├── config.json       # Project configuration + safety limits
  ├── STATE.md          # Current project state (<100 lines, always current)
  ├── CONTEXT.md        # Locked decisions all agents must respect
  ├── PLAN.md           # XML-structured task plan with waves
  ├── CONSTITUTION.md   # Project-level non-negotiable principles
  ├── HEARTBEAT.md      # What the heartbeat daemon should check
  ├── tasks.jsonl       # Append-only task event log
  ├── sessions/         # Agent session data
  ├── memory/           # Per-agent persistent memory
  └── worktrees/        # Git worktree directories per agent

Inspiration & Credits

slavedriver stands on the shoulders of these projects:

| Project | What We Took | License | |---------|-------------|---------| | GSD | Wave execution, fresh context per task, atomic commits, .planning/ pattern | MIT | | OpenClaw | Heartbeat daemon, skills system, file-based state philosophy | MIT | | Ralph Wiggum Loop | Iterative self-improvement loop, worker/reviewer dual-model, git-as-memory | MIT | | Goose | MCP extension system, recipe format, permission modes, subagent limits | Apache 2.0 | | Warp Terminal | Block-based output, tiered approval UX, agent management panel, Oz orchestration | Proprietary | | BMAD | Artifact-first development, quality gates, agent roles | MIT | | Spec Kit | Spec-driven workflow, phase context templates | MIT | | Claude Code | Git worktree isolation, orchestrator-worker, hooks system, stream JSON | — | | Claude Cowork | No-code plugin system, VM sandboxing, two-tier parallelism, 15+ lifecycle hooks | — | | CrewAI | Role-based agents, crew/flow hybrid, YAML agent definitions | Apache 2.0 | | Devin | Four-tab workspace, following toggle, auto-proceed approval, machine snapshots | Proprietary | | Cursor | Agent sessions sidebar, parallel agents, aggregated diff view | Proprietary | | LangGraph Studio | Time travel / state forking, graph-as-execution-trace | MIT |

Documentation

• Architecture — Full system design, interfaces, state machines
• Requirements — All v1 requirements with IDs
• Roadmap — Phased milestones and success criteria
• Stack — Technology decisions and rationale
• Conventions — Coding standards and patterns
• Research — Framework analysis and pattern extraction
• References — Deep implementation references from all inspiration projects
• Project State — Current status and open questions
• Constitution — Non-negotiable project principles

License

MIT