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.

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):

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 partial results if a run is killed)
• error.json — error details (only on failure)

Result status: consensus | partial_consensus | unresolved | interrupted | failed.

If a debate drops below the required participant count, prefer the default interrupted path so downstream tools still get a structured result. Only force onInsufficientParticipants: "fail" when the caller explicitly needs legacy hard-failure semantics.

If you need to parse result.json programmatically, the canonical schema lives at `packages/argue/src/contracts/result.ts`.

Tips

1. Frame as decisions, not topics. "Should we use SwiftUI or UIKit?" beats "Tell me about SwiftUI". 2. Add context. "Should we use a monorepo? Context: 8 microservices, 3 teams, Node+Go" produces sharper claims. 3. 2–3 agents is the sweet spot. Agents in the same round are dispatched in parallel, so wall-clock is dominated by rounds rather than agent count — adding more agents barely costs time. The real cost is tokens: every extra agent produces its own claims, plus every other agent has to read them as peer context, so token usage grows roughly with N². If the user's config has more than 3 agents, pass --agents a,b,c explicitly to pick a focused subset, or set defaults.defaultAgents in the config file once. 4. Use `--action` when consensus should drive code changes or another real-world side-effect.

Troubleshooting

For common errors and fixes, see references/troubleshooting.md.

Argue Setup & Configuration

Config Location & Precedence

Argue uses a JSON config file. Lookup order (highest priority first):

1. CLI flags (--config <path>) 2. Project-local: ./argue.config.json 3. Global: ~/.config/argue/config.json

Init Commands

# Project-local config (recommended for repos)
argue config init --local

# Global config (for general use)
argue config init --global

# Custom path
argue config init -c /path/to/config.json

Provider Types

CLI-based providers (recommended)

Agents run via their respective CLIs — no API keys needed if you're already authenticated:

# OpenAI Codex CLI
argue config add-provider --id codex --type cli --cli-type codex --model-id gpt-5.4

# Google Gemini CLI
argue config add-provider --id gemini --type cli --cli-type gemini --model-id gemini-3.1-pro-preview

# Anthropic Claude CLI
argue config add-provider --id claude --type cli --cli-type claude --model-id claude-4-sonnet

# GitHub Copilot CLI
argue config add-provider --id copilot --type cli --cli-type copilot --model-id gpt-5.4

# Other CLI types: pi, opencode, droid, amp, generic

For generic CLI type, specify --command and --args:

argue config add-provider --id custom --type cli --cli-type generic --command my-cli --args "--model,model-name"

API-based providers

For direct API access without a CLI. Use --vendor for presets or --protocol for custom endpoints:

# Vendor presets (auto-fill protocol, baseUrl, apiKeyEnv):
# Anthropic (uses ANTHROPIC_API_KEY)
argue config add-provider --id anthropic --type api --vendor anthropic --model-id claude-4-sonnet

# OpenAI (uses OPENAI_API_KEY)
argue config add-provider --id openai --type api --vendor openai --model-id gpt-5.4

# Other vendors: groq, together, mistral, deepseek

# OpenAI-compatible endpoint (Ollama, vLLM, etc.)
argue config add-provider --id local \
  --type api --protocol openai-compatible \
  --base-url http://localhost:11434/v1 \
  --model-id llama3

# Anthropic-compatible endpoint
argue config add-provider --id anthropic-proxy \
  --type api --protocol anthropic-compatible \
  --base-url https://my-proxy.example.com \
  --model-id claude-4-sonnet

# Custom API key env var
argue config add-provider --id custom-api --type api --protocol openai-compatible \
  --base-url https://api.example.com/v1 --api-key-env MY_API_KEY --model-id my-model

SDK-based providers

For custom adapters loaded from Node modules:

argue config add-provider --id my-sdk --type sdk --adapter ./my-adapter.js --model-id my-model
# With custom export name:
argue config add-provider --id my-sdk --type sdk --adapter ./my-adapter.js --export-name createMyProvider --model-id my-model

Mock provider (testing)

argue config add-provider --id mock --type mock --model-id test

Adding Agents

Agents reference providers and specify which model to use:

# Basic agent
argue config add-agent --id codex-agent --provider codex --model gpt-5.4

# Agent with role (affects debate behavior)
argue config add-agent --id devil-agent --provider claude --model claude-4-sonnet --role "devil's advocate"

# Agent with custom system prompt
argue config add-agent --id expert-agent --provider gemini --model gemini-3.1-pro-preview --system-prompt "You are a senior architect with 20 years experience."

# Agent with temperature and timeout
argue config add-agent --id creative-agent --provider openai --model gpt-5.4 --temperature 0.9 --timeout-ms 120000

Shorthand: Provider + Agent in One Command

Add --agent <id> to add-provider to create both at once:

argue config add-provider --id codex --type cli --cli-type codex --model-id gpt-5.4 --agent codex-agent

Provider-Model Aliasing

Use --provider-model to map a generic model ID to the provider's actual model name:

argue config add-provider --id codex --type cli --cli-type codex --model-id gpt5 --provider-model gpt-5.4

Removing Providers/Agents

No CLI command exists for removal. Edit the config file directly:

# Edit with your preferred editor
code ~/.config/argue/config.json
# or for project-local
code ./argue.config.json

Remove entries from the providers object or agents array, then save.

Config Schema (v1)

{
  "schemaVersion": 1,
  "providers": {
    "<provider-id>": {
      "type": "cli|api|sdk|mock",
      "cliType": "codex|claude|gemini|...",
      "command": "optional-binary-name",
      "args": [],
      "models": {
        "<model-id>": { "providerModel": "optional-actual-model-name" }
      }
    }
  },
  "agents": [
    {
      "id": "<agent-id>",
      "provider": "<provider-id>",
      "model": "<model-id>",
      "role": "optional-role-description",
      "systemPrompt": "optional-system-prompt",
      "timeoutMs": 120000,
      "temperature": 0.7
    }
  ],
  "defaults": {
    "defaultAgents": ["agent-1", "agent-2"],
    "language": "optional-locale",
    "tokenBudgetHint": 100000,
    "minRounds": 2,
    "maxRounds": 3,
    "perTaskTimeoutMs": 1200000,
    "perRoundTimeoutMs": 1200000,
    "globalDeadlineMs": 3600000,
    "consensusThreshold": 1,
    "composer": "representative",
    "representativeId": "optional-agent-id",
    "includeDeliberationTrace": false,
    "traceLevel": "compact"
  },
  "output": {
    "jsonlPath": "optional-path",
    "resultPath": "optional-path",
    "summaryPath": "optional-path"
  },
  "viewer": {
    "url": "https://argue.onev.cat/"
  }
}

viewer.url overrides the hosted viewer for argue view / --view. Defaults to https://argue.onev.cat/. Must be https://, except http://localhost / 127.0.0.1 for local viewer development. CLI flag --viewer-url <url> overrides per-run.

Composer Options

• `representative` (default): The highest-scoring agent writes the final report. Override which agent composes it with --representative-id <agent-id>.
• `builtin`: Synthesized summary from all agents' contributions, no per-agent representative narration.

argue run --task "..." --composer builtin

Argue Troubleshooting

Common Errors

Output Path Behavior

Output directory depends on which config file argue loads:

• Global config (~/.config/argue/config.json): outputs to ~/.argue/output/<requestId>/
• Project-local config (./argue.config.json): outputs to ./out/<requestId>/

Override with --jsonl, --result, --summary flags.

Debugging Tips

1. Use `--verbose` while learning or debugging to see agent reasoning, claims, and votes in real-time. Skip it for quieter output. 2. Use `--trace --trace-level full` for protocol-level debugging if agents aren't responding. 3. Check `events.jsonl` for the full event stream — includes per-round details and error traces. 4. Check `result.json` for structured output including final status, scores, and claim resolutions. 5. Verify CLI auth separately — run each provider CLI standalone before using it in argue:

   codex "Hello, respond with OK"
   gemini "Hello, respond with OK"

6. Start simple — 2 agents, 2-3 rounds, then increase complexity if needed.

Performance Notes

• 2 agents × 3 rounds ≈ 3-5 minutes (CLI-based providers)
• 2 agents × 3 rounds ≈ 2-4 minutes (API-based providers, no CLI overhead)
• Adding more agents barely affects wall-clock time — each round's participants are dispatched in parallel, so wall-clock is dominated by the slowest agent per round × number of rounds. Adding agents primarily costs tokens, not time: each extra agent produces its own claims and every other agent has to read them as peer context, so token usage grows roughly with N². Use 2–3 agents unless you have a specific reason to fan out wider.
• Very complex topics with long responses may need --per-round-timeout-ms 2400000 (40 min) or higher — the 20 min default is enough for most debates but can clip agents doing deep analysis
• Network issues with API providers can cause intermittent agent failures — retry usually works
• Use --token-budget to cap per-agent token usage for faster debates on constrained topics
• Use --global-deadline-ms to enforce a hard deadline across the entire debate