owl

Parliament of Owls

Query multiple LLMs and deep research APIs in parallel.
Post each response as a comment on a GitHub Issue.

---

Built on Simon Willison's llm for standard model access, with direct API integrations for deep research endpoints. Supports dozens of free models via OpenRouter.

Install

# From source
pip install -e .

# Or globally with pipx (recommended)
pipx install .

Quick Start

# 1. Configure your council (interactive picker)
owl council

# 2. Ask the council
owl ask "What are the tradeoffs between Redis and Memcached for session storage?"

# 3. Read from a file
owl ask -f research_question.md

# 4. Pipe from stdin
echo "Explain quantum computing" | owl ask

# 5. Post to a GitHub issue
owl ask "..." --gh owner/repo
owl ask "..." --gh owner/repo --issue 42

Setting Up Models

Standard Models (via llm)

Install llm plugins and set their API keys:

# OpenAI
llm install llm-openai          # included by default with llm
llm keys set openai              # paste your OpenAI API key

# Anthropic (Claude)
llm install llm-anthropic
llm keys set anthropic           # paste your Anthropic API key

# Google Gemini
llm install llm-gemini
llm keys set gemini              # paste your Google AI API key

# Mistral
llm install llm-mistral
llm keys set mistral             # paste your Mistral API key

# Grok (xAI)
llm install llm-grok
llm keys set grok                # paste your xAI API key

# DeepSeek
llm install llm-deepseek
llm keys set deepseek            # paste your DeepSeek API key

# Cohere
llm install llm-command-r
llm keys set cohere              # paste your Cohere API key

# OpenRouter (dozens of models, many free — no credit card needed)
llm install llm-openrouter
llm keys set openrouter          # paste your OpenRouter API key

# Local models via Ollama
llm install llm-ollama
# No key needed — just have Ollama running

Verify your installed models:

llm models                       # list all available models

Keys are stored in ~/Library/Application Support/io.datasette.llm/keys.json (macOS) or ~/.config/io.datasette.llm/keys.json (Linux).

You can also pass keys via environment variables (e.g. OPENAI_API_KEY) or inline with --key.

See the full llm plugin directory for more providers.

Free Models via OpenRouter

Sign up at openrouter.ai (no credit card required) and get a free API key. Many powerful models are completely free:

• Claude 4.6 Opus / Claude 4.5 Sonnet (Anthropic)
• GPT-5 Nano / GPT-4o Mini (OpenAI)
• Gemini 3 Flash / Gemma 3 27B (Google)
• Grok 4.1 Fast (xAI)
• DeepSeek V3.2 (DeepSeek)
• GLM-4.5 Air (Z.ai)
• Llama 3.3 70B (Meta)
• Mistral Small 3.1 (Mistral)
• Many more — run llm models | grep ":free" to see all

Rate limits: ~20 req/min, ~200 req/day per free model. Owl staggers requests to stay within limits.

Deep Research APIs

Deep research models use direct API calls (not llm plugins). Set their keys as environment variables:

export OPENAI_API_KEY=sk-...        # o3-deep-research, o4-mini-deep-research
export PERPLEXITY_API_KEY=pplx-...  # sonar-deep-research
export GOOGLE_API_KEY=AI...         # Gemini Deep Research Agent
export DEEPSEEK_API_KEY=sk-...      # deepseek-reasoner
export XAI_API_KEY=xai-...          # Grok agentic search

Add these to your ~/.zshrc or ~/.bashrc to persist them.

GitHub Integration

For posting results to GitHub Issues, owl uses your gh CLI auth or a GITHUB_TOKEN:

# Option A: gh CLI (recommended)
gh auth login

# Option B: environment variable
export GITHUB_TOKEN=ghp_...

Commands

owl ask "prompt"                          # Query all council members
owl ask -f prompt.md                      # Read prompt from file
cat prompt.txt | owl ask                  # Read from stdin
owl ask "prompt" --gh owner/repo          # Create new issue with responses
owl ask "prompt" --gh owner/repo --issue 42  # Post to existing issue
owl council                               # Interactive TUI to select council members
owl council-list                          # Show current council
owl models                                # Show all available models

Council Configuration