quorumdeck

A terminal console for running several AI agents — on different models, from different providers — side by side in one session.

Most terminal LLM clients give you one model at a time and a dropdown to switch. quorumdeck starts from the opposite premise: the interesting thing is what happens when a Claude agent, a GPT agent and a local Llama agent all answer the same question at once, and you can see the answers, the latency and the cost next to each other.

Bring your own model. Bring several.

┌─ Claude · anthropic/claude-opus-5 ─┬─ GPT · openai/gpt-5 ───────────────┐
│ › Design a token bucket limiter    │ › Design a token bucket limiter    │
│                                    │                                    │
│ Use a monotonic clock and lazy     │ A token bucket needs four pieces   │
│ refill rather than a background…▌  │ of state: capacity, tokens,…▌      │
│                                    │                                    │
│      1204→318 tok · $0.0089 · 4.1s │      1204→402 tok · $0.0051 · 2.8s │
└────────────────────────────────────┴────────────────────────────────────┘
 ready  ·  fanout × 2  ·  1922 tok  ·  $0.01

Status: alpha. All five orchestration patterns — single, fanout, judge, debate, pipeline — work end to end. See ROADMAP.md for what's next (tool use, session resume).

Why this exists

Install

Requires Python 3.11+.

# Run without installing
uvx quorumdeck

# Or install
uv tool install quorumdeck   # or: pipx install quorumdeck

0.1.0 is a normal release, not a pre-release, so no --prerelease/--pre flag is needed -- but it's still pre-1.0: expect breaking changes to agents.yaml between minor versions until 1.0.

Quick start

deck config init                 # writes ~/.config/quorumdeck/agents.yaml
deck keys set anthropic          # prompts; stored in the OS keychain
deck                             # launch the TUI

One-shot, no UI — pipes and scripts welcome:

deck run "Explain this stack trace" < trace.txt
deck run --pattern fanout "Which index would you add here?"

Configuring a deck

agents.yaml is the whole interface. Precedence: --config → ./quorumdeck.yaml → ~/.config/quorumdeck/agents.yaml.

version: 1

deck:
  pattern: fanout        # single | fanout | debate | pipeline | judge
  title: Compare

defaults:
  temperature: 0.7
  timeout_s: 120

agents:
  - id: claude
    name: Claude
    model: anthropic/claude-opus-5
    system_prompt: Answer concisely. Show the tradeoff, not just the answer.

  - id: gpt
    name: GPT
    model: openai/gpt-5

  - id: local
    name: Local
    model: ollama_chat/llama3.3
    api_base: http://localhost:11434

Model ids are LiteLLM ids: provider/model. More in examples/.

Fully local

examples/ollama.yaml compares three small models on a running Ollama — no API key, no account, and no network:

ollama serve
deck --config examples/ollama.yaml

Use the ollama_chat/ prefix rather than ollama/: it routes to Ollama's /api/chat endpoint, which keeps a multi-turn conversation intact. A deck whose agents are all local skips LiteLLM's remote price list too, so it stays offline end to end.

Free, but not local

examples/judge.yaml, examples/debate.yaml and examples/pipeline.yaml run entirely on OpenRouter's free tier — several models from different labs, one key, no card:

deck keys set openrouter        # from https://openrouter.ai/keys
deck --config examples/judge.yaml
deck --config examples/debate.yaml
deck --config examples/pipeline.yaml

Or set OPENROUTER_API_KEY in the environment instead; it takes precedence over the keychain. See Keys for the full prefix-to-variable table.

Free model ids rotate, so if one 404s pick a live replacement from openrouter.ai/models?q=free; no pattern depends on a particular model.

Orchestration patterns

The schema was written to validate all five before any of them had a runtime, on purpose — a pattern's config shape doesn't change the day its _run_* method lands, and a request for one not yet built fails clearly rather than silently falling back to another.

Keys

deck keys list                   # where each provider's key comes from
deck keys set openai             # store in the OS keychain (never echoed)
deck keys rm openai

An environment variable always wins over the keychain, so CI and containers work without a keyring backend. The variable is chosen by the model id's prefix:

So examples/judge.yaml, whose models all start openrouter/, needs one variable:

export OPENROUTER_API_KEY=sk-or-...     # or: deck keys set openrouter
deck --config examples/judge.yaml

A model id with no prefix at all (gpt-5 rather than openai/gpt-5) is treated as OpenAI, matching LiteLLM's own default. For a prefix outside this table, set whatever variable LiteLLM expects for that backend yourself. deck keys set rejects a provider outside this table rather than storing a key it could never export, and it does so before prompting, so a typo never costs you a pasted secret. deck keys rm stays permissive, so an entry stored under an old name can still be cleaned up.

ollama, ollama_chat, vllm, lm_studio, bedrock and sagemaker need no key at all: they authenticate over a local socket or through a credential chain.

deck keys list shows, per provider, whether the key is coming from the environment, the keychain, or nowhere.

Keyboard

A deck opens in Textual's tokyo-night theme -- several panels are read at once, and it holds contrast between them better than Textual's default. The command palette (ctrl+p) switches to any of Textual's other built-in themes for the session; there is no config option for it yet.

Architecture

The layering is the load-bearing decision, not an aesthetic one:

src/quorumdeck/
  core/        agent · orchestrator · session · events · messages · costs
  providers/   base (the port) · litellm_provider (the only adapter today)
  config/      schema (pydantic) · loader · secrets (keychain)
  tui/         app · widgets · screens
  cli.py

Two rules hold it together, and both are enforced by the test suite:

1. core/ imports no vendor SDK and no UI framework. It is pure async Python over its own event vocabulary, which is why every orchestration pattern is testable against a scripted fake provider with no network.
2. tui/ imports no provider. It consumes core events. Adding a backend never touches the UI; adding a UI never touches a backend.

If LiteLLM turns out to be the wrong engine, replacing it means writing one new module in providers/ that satisfies the Provider protocol — roughly 80 lines — and changing nothing else.

Development

uv sync
uv run pytest
uv run ruff check .
uv run textual run --dev quorumdeck.tui.app:QuorumDeckApp   # with devtools

Contributions welcome — see CONTRIBUTING.md. The most useful places to start are listed in ROADMAP.md.

License

MIT. See LICENSE.