Your AI dev team — not one agent, but a crew.

Planner breaks it down · Coder builds it · Reviewer challenges it · Tester validates it

Try the demo (no API key) • How it works • The debate system • Interactive mode • Configuration

Try it in 10 seconds

No API key required. Watch a complete debate loop — Planner → Coder → Reviewer → debate → Tester — right in your terminal:

npx codequorum --demo

This runs a scripted scenario ("Build a hello world CLI") using a mock provider. You'll see the Reviewer reject the Coder's first attempt, the Coder push back on one point with technical reasoning, and the Reviewer concede when the argument holds. Under 15 seconds, zero cost, zero config.

Why CodeQuorum?

Single-agent coding tools write code. CodeQuorum develops code.

| | Single Agent | CodeQuorum | | -------------- | ---------------------- | -------------------------------- | | Architecture | Just starts coding | Plans first, then codes | | Quality | No review | Code review with debate | | Bugs | Caught later (if ever) | Caught by Reviewer before ship | | Tests | Maybe | Always | | Process | Black box | Transparent team discussion | | Disagreements | Silent | Debated out in the open |

Quick Start (real tasks)

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# Run CodeQuorum on your own task
npx codequorum "Build a REST API for managing todos with SQLite"

That's it. Watch four agents collaborate, debate, and produce code in ./output/.

How It Works

User Task
    │
    ▼
┌─────────┐
│ PLANNER │ ── breaks task into architectural specs
└────┬────┘
     │
     ▼
┌─────────┐
│  CODER  │ ── implements the specs
└────┬────┘
     │
     ▼
┌──────────┐     ┌──────────────────────────┐
│ REVIEWER │────►│ APPROVED? ──► TESTER     │
└────┬─────┘     └──────────────────────────┘
     │ CHANGES_REQUESTED
     ▼
┌─────────┐
│  CODER  │ ── addresses feedback (can push back!)
└────┬────┘
     │
     ▼
  [Loop up to maxDebateRounds]

Agents

📋 Planner

Analyzes your request, designs the architecture, and writes detailed specs for every file. Thinks like a senior tech lead writing a design doc.

💻 Coder

Implements the specs with production-quality code. Writes clean, well-typed, documented code with proper error handling.

🔍 Reviewer

Reviews code like a senior engineer. Catches bugs, security issues, performance problems, and style violations. Won't approve mediocre code.

🧪 Tester

Writes comprehensive tests covering happy paths, edge cases, error scenarios, and boundary conditions. Reports coverage gaps.

The Debate System 🔥

This is what makes CodeQuorum unique. When the Reviewer requests changes:

1. The Coder addresses the feedback — but can also push back with technical arguments
2. The Reviewer considers the arguments and re-evaluates
3. This continues until consensus (or max rounds)

Real teams debate. So does CodeQuorum.

CLI Options

npx codequorum "Your task" [options]

Options:
  -p, --provider <p>   LLM provider: anthropic | openai | ollama
  -m, --model <name>   Model name (defaults to provider's best model)
  -r, --max-rounds <n> Max debate rounds (default: 3)
  -o, --output <dir>   Output directory (default: ./output)
  -c, --config <path>  Path to codequorum.config.js
  -v, --verbose        Verbose output
  --api-key <key>      API key (overrides env variable)
  --base-url <url>     Custom API base URL
  --dry-run            Run agents without writing files
  --diff               Show diff preview before writing
  --resume <id>        Resume an interrupted session
  -i, --interactive    Edit the Planner's plan before Coder starts
  --demo               Run a scripted demo without an API key

Configuration

Create a codequorum.config.js in your project root:

import { defineConfig } from "codequorum";

export default defineConfig({
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  maxDebateRounds: 5,
  agents: ["planner", "coder", "reviewer", "tester"],
  outputDir: "./src",
  temperature: 0.7,
});

Providers

Works with any LLM:

• Anthropic Claude (recommended) — set ANTHROPIC_API_KEY
• OpenAI GPT-4 — set OPENAI_API_KEY
• Ollama (local, free) — run ollama serve first
• Any OpenAI-compatible API via --base-url

Advanced Features

💰 Cost Transparency

Every run shows actual token usage and dollar cost per agent:

╭──────────────────────────────────────╮
│  💰 Cost Breakdown                   │
│  📋 Planner:  1,200 tokens  $0.0042  │
│  💻 Coder:    3,400 tokens  $0.0156  │
│  🔍 Reviewer: 1,800 tokens  $0.0078  │
│  🧪 Tester:   2,100 tokens  $0.0089  │
│  Total:       8,500 tokens  $0.0365  │
╰──────────────────────────────────────╯

🏃 Dry Run Mode

Preview what agents would produce without writing anything to disk:

npx codequorum "Refactor user module" --dry-run

📄 Diff Mode

Show a colored diff preview and confirm before writing:

npx codequorum "Fix the auth bug" --diff

✋ Interactive Plan Editing

You're in charge, not the AI. Review and edit the Planner's plan in your $EDITOR before the Coder starts:

npx codequorum "Build a REST API for todos" --interactive

After the Planner finishes, you'll see:

✋ Interactive mode — review the plan before coding
Press Enter to accept, or type 'e' to edit the plan in your $EDITOR.

Edit plan before Coder starts? [y/N/e(dit)]:

Type e, make your changes, save, and exit. The Coder will implement your edited plan, not the original. Respects $VISUAL and $EDITOR environment variables — works with vim, nano, emacs, code --wait, cursor --wait, and more.

🔄 Session Resume

Interrupted runs save their progress automatically. Resume from where you left off:

npx codequorum --resume <session-id>

🔁 Automatic Retry

Transient API failures (rate limits, server errors) are retried automatically with exponential backoff (1s → 2s → 4s).

Programmatic API

import { Crew, defineConfig } from "codequorum";
import { AnthropicProvider } from "codequorum/providers/anthropic.js";

const config = defineConfig({
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  maxDebateRounds: 3,
});

const provider = new AnthropicProvider(config);
const crew = new Crew(config, provider);

const result = await crew.run("Build a REST API for todos");
console.log(`Generated ${result.files.length} files`);
console.log(`Cost: $${result.stats.costEstimate.totalCost}`);

Contributing

Contributions welcome! Please open an issue to discuss major changes first.

License

MIT — see LICENSE for details.