convez.ai
AgenteAutomaçãoAvançado
sensiloles

Agent Quorum

sensiloles/agent-quorum

Painel de agentes com crítica adversarial para planos de código validados

Ver no GitHub
BomPluginScore · de 0 a 100

Orquestrador que executa um painel de agentes em loop iterativo de plano → crítica → atualização para gerar planos de implementação robustos e auto-revisados. Integra múltiplos provedores (Codex, Claude, Cursor) com validação de referências e convergência garantida, eliminando a confiança em um único agente.

Instalação

$npx convez-ai sensiloles/agent-quorum

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
9
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v0.8.0
Issues abertas
16
Contribuidores
1

Casos de uso

  • Gerar planos de implementação complexos com múltiplas fases e validação automática
  • Orquestrar revisão iterativa entre agentes com diferentes modelos e capacidades
  • Decompor tarefas grandes em pacotes executáveis para modelos mais fracos

Veredito

Ferramenta sofisticada para quem precisa de planos rigorosos e auto-validados em vez de drafts únicos. Ideal para arquitetos de sistema que orquestram múltiplos agentes, mas exige compreensão profunda de fluxos multi-agente e configuração declarativa.

README

A tradução para o português deste README ainda está na fila.

agent-quorum

npm version

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

OSStatusCI
macOS 13+Supportedmacos-latest
Linux (glibc)Supportedubuntu-latest
WindowsNot 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

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:

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

Ver o original no GitHub

Bom para

Relacionados