/argue

name: argue
description: "Run structured multi-agent debates using argue CLI for cross-examined, high-confidence answers. Use when facing strategic decisions, ambiguous trade-offs, architecture debates, or questions where multiple perspectives improve the answer. Triggers on: argue, debate, cross-examine, second opinion, multi-agent, 'Should we X or Y?' with real stakes, consensus-building, risk analysis, or confirmation-bias mitigation."
license: MIT
compatibility: "Requires argue CLI (@onevcat/argue-cli v0.2+) and at least 2 configured agents. CLI-based providers need their respective CLIs installed (codex, gemini, claude, etc.). API-based providers need API keys in environment."
metadata: { "author": "onevcat", "repo": "https://github.com/onevcat/argue" }

Argue — Multi-Agent Debate Engine

Structured debates where AI agents analyze independently, cross-examine across rounds, and converge on consensus through voting. Higher-confidence answers than any single model alone.

When to Use

✅ Strategic / architectural decisions with real trade-offs, "Should we X or Y?" with real stakes, risk analysis, confirmation-bias mitigation, pre-commit quality gates on big decisions.

❌ Simple factual lookups, time-critical tasks (debates take 3–7 minutes), open-ended creative generation, questions with obvious answers.

Pre-flight

If `argue` is not on PATH, install it (confirm with the user first — this is a global install):

npm install -g @onevcat/argue-cli

Then verify and configure:

argue version                          # verify installed (v0.2+)
argue config init --global             # ~/.config/argue/config.json — recommended for agent use

# Add at least 2 agents — `--agent <id>` shorthand creates provider + agent in one shot
argue config add-provider --id codex  --type cli --cli-type codex  --model-id gpt-5.4 --agent codex-agent
argue config add-provider --id gemini --type cli --cli-type gemini --model-id gemini-3.1-pro-preview --agent gemini-agent

**Why global by default**: a global config is set up once and works from any cwd, and outputs go to `~/.argue/output/<requestId>/` instead of cluttering the current project tree. Use `argue config init --local` only when a specific project needs its own dedicated agent line-up — that writes `./argue.config.json` and outputs to `./out/<requestId>/`.

For API providers, SDK adapters, roles, and system prompts, see [references/setup.md](references/setup.md).

Running Debates

# Basic — 2 agents, 2-3 rounds, auto-consensus
argue run --task "Should we use a monorepo or polyrepo?" --verbose

# With a follow-up action: representative executes once consensus is reached
argue run \
  --task "Review the API design in docs/api.md" \
  --action "Implement the consensus recommendation and open a PR" \
  --verbose

# Open the rendered report in the hosted viewer when the run finishes
argue run --task "..." --view

Useful flags (full list: `argue --help`):

| Flag | Purpose | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | `--agents a,b` | Pick which agents participate (default: `defaults.defaultAgents` from config, else **all configured agents**) | | `--min-participants <n>` | Minimum surviving participants required to continue (default: 2) | | `--on-insufficient-participants interrupt\|fail` | When too few participants remain, either emit `interrupted` (default) or fail hard | | `--min-rounds` / `--max-rounds` | Control debate depth (defaults: 2 / 3) | | `--threshold <0..1>` | Consensus threshold (default: 1 = unanimous) | | `--action <prompt>` | Execute task after consensus | | `--view` / `--viewer-url <url>` | Open report in the hosted viewer | | `--input <file>` | JSON input for complex setups | | `--verbose` / `-v` | Stream agent reasoning live |

Debates typically take 3–7 minutes for 2 agents × 3 rounds. Default cap is 20 min per round (and per task, which tracks the round cap by default); bump `--per-round-timeout-ms` for heavy reviews.

Viewing & Acting on Results

When a run finishes, argue prints the request id and a viewer hint. Open it any time:

argue view                  # most recent run
argue view <request-id>     # specific run

The hosted viewer renders `result.json` entirely client-side (gzip + base64url in the URL fragment — nothing is uploaded). Use `--viewer-url` to point at a self-hosted viewer.

To run a follow-up task using a debate result as context:

argue act --result ~/.argue/output/<requestId>/result.json --task "Write a summary blog post"
argue act --result ./out/<requestId>/result.json --task "Implement the changes" --agent codex-agent

Output Files

After every run, argue writes to `~/.argue/output/<requestId>/` (global config) or `./out/<requestId>/` (project-local config):

• `result.json` — full structured result
• `summary.md` — markdown report (written on completion)
• `events.jsonl` — event stream (written live, survives crashes — parse it for partia