| name | ora-usage |
| description | Use when running ORA (Open Research Agent) CLI commands, configuring ORA, understanding intensity levels, troubleshooting ORA errors, or when asked to research a topic with ORA. Triggers on "ora research", "ora plan", "ora config", "open-research-agent", ORA output files, ORA configuration, or ORA error messages. |
ORA Usage
Overview
ORA is a multi-agent research CLI (v0.1.0) that turns a query into a sourced markdown report. Pipeline: Supervisor plans → Researcher searches and scrapes → Writer synthesizes → Reviewer audits (intensity 3+). Backends: DeepSeek API (LLM), Firecrawl (search/scrape).
Required Setup
export DEEPSEEK_API_KEY="your-key"
export FIRECRAWL_API_KEY="your-key"
ora config --init
For self-hosted Firecrawl: set FIRECRAWL_API_URL=http://localhost:3002.
Quick Reference
| Task | Command |
|---|
| Run research | ora research "query" (default intensity 2) |
| Run at higher intensity | ora research "query" --intensity 4 |
| Preview plan only | ora plan "query" |
| Custom output path | ora research "query" --output path/to/report.md |
| Stdout only, no file | ora research "query" --no-save |
| Skip interactive approval | ora research "query" -y (--auto-approve) |
| Minimal output | ora research "query" --quiet |
| Change researcher model | ora research "query" --model deepseek-v4-chat |
| Change reviewer model | ora research "query" --reviewer-model deepseek-v4-pro |
| Limit reviewer rounds | ora research "query" --max-revisions 2 |
| Show config | ora config --show |
Configuration
Config file: ~/.ora/config.yaml. Priority: env vars > config file > defaults.
models:
default: deepseek-v4-flash
researcher: ~
supervisor: deepseek-v4-pro
reviewer: deepseek-v4-pro
search:
provider: firecrawl
limits:
max_revisions: 3
default_intensity: 2
Change supervisor model only via config file or ORA_MODELS__SUPERVISOR env var.
provider:model prefix (e.g., openai:gpt-4.1) is cosmetic and stripped; everything routes through deepseek_base_url. To use a different provider, change deepseek_base_url in config.
Intensity Levels
| Level | Label | Min Sources | Max Rounds | Reviewer | Search Angles |
|---|
| 1 | Quick | 3 | 5 | No | 1 |
| 2 | Standard | 8 | 5 | No | 3 |
| 3 | Thorough | 15 | 7 | Yes | 7 |
| 4 | Deep | 50 | 10 | Yes | 12 |
| 5 | Exhaustive | 100 | 10 | Yes | 16 |
Reviewer (levels 3+) audits draft and can issue REVISE to restart research (max 3 cycles; cap with --max-revisions). No reviewer at levels 1-2.
Default safe choice: Level 2 for most research. Level 3+ when you need adversarial audit-trail review.
Common Patterns
- Quick fact-check: Intensity 1-2 (no reviewer, 3-8 sources)
- Preview before committing:
ora plan "query" or cancel at interactive prompt
- Batch/scripted: Use
-y (auto-approve) + --quiet + --output
- Model per phase:
--model = researcher + writer; --reviewer-model = reviewer; supervisor via config only
Known Issues (v0.1.0)
--no-review is dead code. Declared but not wired. Only dropping to intensity 2 removes the reviewer.provider:model prefix is cosmetic. Stripped silently; all requests go to DeepSeek.
Common Mistakes
| Mistake | Reality |
|---|
Using --no-review at intensity 3+ | Flag is dead. Drop to intensity 2 instead. |
Passing openai:gpt-4.1 as model name | Prefix stripped, still routes to DeepSeek. Change deepseek_base_url in config. |
Expecting --supervisor-model flag | Does not exist. Use config file or ORA_MODELS__SUPERVISOR. |
Forgetting FIRECRAWL_API_KEY | Required for search/scrape. Report generation fails without it. |
--max-revisions at intensity 1-2 | Only relevant at intensity 3+ (reviewer active). |
| Confused by auto-generated filename | Default: {query-slug}-{timestamp}.md. Use --output to control. |
Red Flags
- "I'll use --no-review" → Dead code. Drop intensity.
- "I'll pass openai:gpt-4" → Prefix is cosmetic. Change base URL.
- "I'll set --supervisor-model" → Flag does not exist. Use config.
- "Report didn't generate" → Check both
DEEPSEEK_API_KEY and FIRECRAWL_API_KEY.
