debatr

Run AI debates from your terminal, and give AI agents a debate tool over MCP.

debatr is the command-line client for Debatr, the AI debate studio: pick a question and the models, watch them argue live in your terminal and get the judge's verdict. The same package is an MCP server, so Claude, Cursor and other agents can stage a debate to stress-test a decision or see both sides of a question.

$ debatr run "Should cities ban cars from their centres?" -d anthropic/claude-sonnet-4.5 -d openai/gpt-5

● The Host  HOST · openrouter/free
Welcome! Today two models take on car-free city centres…

● Nova  PRO · anthropic/claude-sonnet-4.5
Cities belong to people, not parked metal…

● Atlas  CON · openai/gpt-5
A ban hits the people with the fewest alternatives first…

╭─ ⚖ The judge's verdict ─────────────────────────────╮
│ Winner: Nova                                        │
│ Nova grounded every claim in what cities measured.  │
╰─────────────────────────────────────────────────────╯
✓ Completed  ·  7 turns  ·  provider cost $0.0213

Install

uv tool install debatr        # or: pipx install debatr
debatr --help

No install needed for a one-off: uvx debatr run "Tabs or spaces?". Python 3.10+ is required (uv fetches one if you have none).

Sign in

debatr login

This opens Debatr in your browser and asks you to confirm a code (like gh auth login). You can give this computer a spending limit there. The token is saved in ~/.config/debatr/config.json (readable only by you) and can be revoked at any time under Account → API tokens on the website, or with debatr logout.

For CI and scripts, create a token under Account → API tokens and pass it in the environment:

export DEBATR_TOKEN=debatr_…
debatr whoami

A token acts as you for debates and spending, but can never change your password, keys or payments, or create other tokens.

Run a debate

debatr run "Is remote work better for juniors?"                 # two free models
debatr run "Nuclear or renewables?" \
  -d anthropic/claude-sonnet-4.5 -n Ada -s "A nuclear engineer" \
  -d google/gemini-2.5-pro -n Ben -s "A grid operator who favours renewables" \
  --rounds 3 --length medium
debatr run "Should we rewrite it in Rust?" --context "A 40k-line Go service, team of 4" --json
debatr run "Tabs or spaces?" --format rap_battle --rounds 2 --length short   # verses only
debatr run "Tabs or spaces?" --format rap_battle --audio --flow smooth --flow fierce

Every run is estimated first. Free models cost nothing; paid models are charged to your Debatr credits (or to your own OpenRouter key: set DEBATR_OPENROUTER_KEY). Without a terminal (CI, agents), a paid run needs --yes or --max-cost. Press Ctrl+C to stop following a debate: you are asked whether to stop it on the server too.

More commands

DEBATE is an id, a link (…/debate/<id>, …/d/<slug>) or a share slug. Commands that print data accept --json. Exit codes: 0 success, 1 an error or a debate that did not complete, 130 interrupted.

For AI agents (MCP)

debatr mcp runs an MCP server on stdio. Sign in once with debatr login (or pass DEBATR_TOKEN), then add it to your agent:

Claude Code

claude mcp add debatr --scope user -- uvx debatr mcp

Claude Desktop, Cursor, Windsurf and other clients (mcpServers in their config file):

{
  "mcpServers": {
    "debatr": {
      "command": "uvx",
      "args": ["debatr", "mcp"],
      "env": { "DEBATR_MAX_COST_USD": "0.50" }
    }
  }
}

Desktop apps do not always see your shell's PATH: if uvx is not found, use its full path (which uvx). Add "DEBATR_TOKEN": "debatr_…" to env to use a dedicated token instead of your debatr login.

Agents spend your credits only within two limits: the token's own spending limit (set it when you approve debatr login or create the token) and DEBATR_MAX_COST_USD, the most one debate may cost through this server (default 1.00). Debates started by agents are private unless they ask to publish them.

Configuration

Self-hosted Debatr: point the CLI at your server with --url (or DEBATR_URL), e.g. debatr --url http://localhost login. Logins are kept per server.

Development

The package lives in the cli/ folder of the Debatr repository and only uses the public REST API (/api/docs on any Debatr server).

cd cli
uv sync
uv run debatr --url http://localhost --help
uv run pytest -q && uv run ruff check . && uv run pyright

Releases are published to PyPI by GitHub Actions when a cli-vX.Y.Z tag is pushed (the version lives in src/debatr/__init__.py).

License

MIT