agent-quorum

What it does

Turning a rough idea into an implementation plan a coding agent can actually execute is hard: a single agent asked to "write the plan" tends to be confident, shallow, and unchecked — it never argues with itself, and nothing validates that the result is complete or that the file references it cites are real.

agent-quorum closes that gap. Instead of prompting one agent once, it runs a panel of agents in an iterative plan → critique → update loop: one drafts a plan, another tears it apart, the draft is revised against that critique, and the cycle repeats until the criticism runs out. The output is a plan that has survived adversarial review, has every file:line reference checked against your workspace, and is schema-validated at every step — produced without any agent ever being granted a tool that can write to disk.

Use it when you want a thorough, self-reviewed plan rather than a first draft, and you would rather have several agents disagree their way to a good answer than trust a single pass.

How the loop works

You hand agent-quorum a prompt or a rough plan. A creator writes the first draft. A critic then reviews it and reports concrete issues; the creator revises the draft to address them. That review-and-revise cycle repeats until the critic finds nothing left to fix — the point of convergence — at which a reference validator and an optional fix pass clean up the final plan. If the converged plan is large or has many phases, agent-quorum performs a split: it emits a self-contained plan.package/ directory so a weaker model can execute one phase at a time.

Five roles drive that loop: the critic finds issues, the creator drafts and revises, the fixer proposes reference fixes after convergence, the reviewer checks the fixer's proposal, and the translator renders a localized companion plan when you ask for one.

prompt.md
    │
    │  clarify gate · operator answers blocking questions (Telegram)
    │
    ▼
creator ──► plan.v0.md
                │
    ╭───────────┴───────────╮
    │  critic   → critique  │
    │  creator  → revision  │ ◄── operator interventions
    │  …until convergence   │
    ╰───────────┬───────────╯
                ▼
reference validator ──► fix pass ──► plan.final.md
                                           │
                                           │  split policy (large/complex) ──► plan.package/
                                           │  locale pass (when requested)
                                           │
                                           ▼
                              plan.final.<locale>.md

Those five roles map onto three providers (codex, claude, cursor-agent) through a single declarative config, and every provider call runs in its own process group under a byte-idle / semantic-idle / wall-clock watchdog.

Glossary

• role — one job in the loop (critic, creator, fixer, reviewer, translator), each bound to a provider and a prompt skill.
• runner — the provider CLI a role calls: codex, claude, or cursor.
• effort — a preset (low, high, max) that selects the role-call topology and how aggressively provider sessions are reused.
• convergence — the point where the critic finds no remaining blocking issues, so the loop stops and finalizes the plan.
• split — emitting the converged plan as a multi-file plan.package/ when it is large or has enough phases, so it can be executed one phase at a time.

Quickstart

Install the CLI globally:

npm install -g agent-quorum

Prerequisites: Node ≥ 24 and at least one provider CLI (codex, claude, or cursor-agent) installed and authenticated — each selected runner is preflighted before the loop starts, so a missing login fails fast with a remedy hint instead of stalling mid-run.

Create a task prompt and run the loop:

agent-quorum plan --prompt my-task.md

By default the run writes its functional artifacts to ~/.agent-quorum/runs/loop-<name>/ (where <name> derives from the input filename) and its durable run record under ~/.agent-quorum/state/. The files you care about are:

• plan.final.md — the converged plan; always the entry point.
• summary.md — a one-page run summary (iterations, health, artifact paths).
• plan.package/ — present only when the split policy fires; a self-contained directory (index, master plan, per-phase docs, journal, runbook, debt ledger) for phase-by-phase execution.

CLI

A single agent-quorum bin fronts these entry points:

agent-quorum plan my-plan.md                 # core loop over an existing plan
agent-quorum plan --prompt my-prompt.md      # create plan.v0 from a prompt first
agent-quorum launch --effort high task.md    # detached background run + run.log
agent-quorum status                          # pick a run (TTY) or scriptable listing
agent-quorum show <name|id|PID|--last>       # a run's artifact paths and state
agent-quorum logs <selector> [-f]            # print or follow a run's run.log
agent-quorum intervene <selector> "note"     # inject operator guidance mid-run
agent-quorum prune [--keep N] [--dry-run]    # bound the run ledger

Runs are addressable by a durable runId/name selector; see the end-to-end walk-through in docs/run-lifecycle.md. The full flag reference and exit codes live in docs/cli.md, and the plan shape gate that existing plan inputs must satisfy is documented in docs/architecture.md#plan-shape-contract. Non-English locales localize Telegram clarification questions and produce plan.final.<locale>.md; Telegram credentials also enable concise final completion notifications for core runs.

Library

import { runPlanLoop, getRunStatus, addIntervention, ExitCode } from 'agent-quorum';

const result = await runPlanLoop({ input: 'my-plan.md', iters: 3, effort: 'high' });
if (result.exitCode === ExitCode.Ok) {
  console.log(`converged in ${result.iterations} iterations: ${result.finalPlanPath}`);
}

The API returns results — only the CLI calls process.exit. runPlanLoop returns a structured result (workDir, finalPlanPath, summaryPath, iterations, health) built from the same data as summary.md. See docs/api.md for the full surface, including CommonJS use.

Configuration

agent-quorum reads one config file: the packaged agent-quorum.json, or the file pointed at by AGENT_QUORUM_CONFIG_FILE. There is no search chain. It has two main sections: settings (iteration cap, effort, fix pass, locale, translation, retries) and roles (per-role runner, model, reasoning level, and tool permissions). Supported runners are codex, claude, and cursor.

A gitignored package-root .env is loaded before config resolution, with real environment variables winning. It is intended for secrets such as Telegram bot credentials, which enable final completion notifications automatically; set AGENT_QUORUM_CLARIFY=0 for notifications without the prompt-mode question gate.

The full reference — every AGENT_QUORUM_* variable, watchdog knob, Telegram setting, status/launch toggle, and the exact CLI > env > file override precedence — lives in docs/configuration.md.

Platform support

| OS | Status | CI | | ------------- | ------------- | --------------- | | macOS 13+ | Supported | macos-latest | | Linux (glibc) | Supported | ubuntu-latest | | Windows | Not supported | — |

Both macOS and Linux are tested on every push and pull request via the full pnpm run check matrix (build · typecheck · lint · format · tests). Install the provider CLIs you plan to use (npm install -g @anthropic-ai/claude-code, npm install -g @openai/codex) and authenticate each. cursor-agent has no official Linux package yet; point AGENT_QUORUM_CURSOR_BIN at your Cursor headless binary to use the cursor runner there (see docs/configuration.md). agent-quorum status uses lsof to resolve a running session's workdir when --work is omitted and degrades gracefully without it (see docs/cli.md).

Documentation

• docs/architecture.md — roles, providers, loop mechanics, artifact contract, watchdog, sessions.
• docs/configuration.md — agent-quorum.json and the environment-variable surface.
• docs/cli.md — entry points, flags, exit codes.
• docs/api.md — typed API and CommonJS consumption.
• docs/release.md — release flow across git tags, GitHub Actions, GitHub Releases, and npm.
• docs/development/conventions.md — code, git, and verification conventions.
• docs/development/agent-skill-flow.md — repository-local requirements, handoff, prompt architecture, execution, and self-planning workflow.
• docs/development/worktree-selection-gate.md — the upfront target-worktree selection protocol shared by tidy, ship, and execute.
• Session Worktrees — the per-session worktree lifecycle (worktree:create, worktree:list, worktree:touch, worktree:done, worktree:reopen, worktree:release) that isolates concurrent sessions.
• examples/ — runnable CLI and API walkthroughs of the loop.

Development

corepack enable
pnpm install --frozen-lockfile
pnpm run check          # typecheck + lint + format check + tests with coverage

Code style, git, and verification rules live in docs/development/conventions.md.

Work is tracked on the public agent-quorum delivery board: Backlog → Todo → In Progress → Done. The /issues skill files session follow-ups straight into the backlog, where they enter the delivery flow (docs/development/agent-skill-flow.md).

For changes that should be designed by agent-quorum itself, dogfood the loop through the agent-quorum bin straight from source — see examples/ for the full CLI and API walkthrough:

pnpm run plan:self -- --prompt .agents/prompts/<slug>.md

plan:self runs src/cli/main.ts via tsx (no build), points run artifacts at .agents/plans/, and accepts the usual --effort, --iters, --locale, --translate, and --fix / --no-fix flags; set AGENT_QUORUM_WORK_DIR to pin a workdir name.

Artifact ownership:

| Path | Role | | ----------------------------- | ------------------------------------ | | .agents/plans/ | Generated run artifacts; ignored. | | .agents/prompts/ | Generated prompts; ignored. | | .agents/requirements/ | Generated requirements; ignored. | | .agents/execution-journals/ | Generated execute journals; ignored. | | .agents/skills/ | Repository-local skill source. | | .claude/commands/ | Mirrored Claude command source. |

License

MIT © Aleksei Filippov