deep-report 0.1.7

Multi-agent research report generator powered by Claude

Deep Report

Multi-agent research reports, powered by Claude.

Deep Report spawns parallel Claude Code agents that search the web, academic databases, papers, and your own references — then synthesizes their findings into a single, citation-grounded report (typically 15–30k words).

Install

pipx install deep-report

Requires Python 3.11+ and Claude Code installed and authenticated.

On Windows, run from Windows Terminal, PowerShell, or cmd.exe — the interactive wizard relies on raw arrow-key input. Git Bash / MSYS2 breaks arrow keys (all keys map to "toggle current row"); use one of the supported shells instead.

Use

Just run it with a topic — that's the whole thing:

deep-report "any topic you want a deep report on"

The CLI walks you through everything else. It picks a sensible number of agents, asks what audience the report is for, suggests report formats that fit your topic, and lets you tweak anything before kicking off. If you don't know which flags to use — don't use any. The interactive interview is the main way to drive the tool.

For repeat runs, --quick skips the interview and uses smart defaults:

deep-report "any topic you want a deep report on" --quick

First-run setup

The first time you run deep-report, you'll be walked through a one-time MCP picker — a checkbox UI for choosing which search engines, paper databases, and scraping tools you want it to use. Nothing is pre-selected; tick what you want.

If you already have MCP servers configured in Claude Code (~/.claude.json or .mcp.json), the wizard offers to import them — no re-entering keys.

Re-run any time with deep-report --setup.

What MCPs are available

MCP	Needs	Tier	What it does
Brave Search	Node	Free tier — 2k queries/mo	Web search with date + locale filters
Exa	Node	Free tier — $10 credit on signup	Full-text semantic search (great for deep research)
Firecrawl	Node	Free tier — 500 pages/mo	Search + scrape with anti-bot handling
Tavily	—	Free tier — 1k credits/mo	Agent-tuned search + extract + crawl
PubMed + Europe PMC	Node	Free	PubMed, bioRxiv, medRxiv, full-text via EPMC
OpenAlex	Node	Free	270M scholarly works + citation graph
arXiv	Python+uv	Free	Search, download, and read CS/physics/math papers
Wikipedia	Python+uv	Free	Universal grounding layer
Context7	Node	Free	Version-pinned library/API docs (essential for tech topics)
Playwright	Node	Free	JS-heavy / anti-bot scrape fallback
crawl4ai	Docker	Free (Docker)	Alternative scraper

The free-tier ones need an API key — the wizard tells you exactly where to sign up. Anything you don't enable is simply skipped; you control what runs and what costs you. There are no paid-only MCPs in the default catalog.

Claude Code skill

Get a /deep-report slash command in Claude Code:

deep-report --install-skill

Then in Claude Code: /deep-report "topic".

Commands

Command	What it does
deep-report "topic"	Run a report with the interactive interview
deep-report "topic" --quick	Skip the interview, use smart defaults
deep-report --setup	Open the MCP picker / re-import from Claude Code
deep-report --list	Pick an unfinished report and resume it
deep-report --intro	Show the onboarding guide
deep-report --update	Pull latest from GitHub
deep-report --install-skill	Install the /deep-report Claude Code skill
deep-report --help	Full flag reference

Output

Each report lands in its own folder:

your-topic_20260523_1430/
├── report.md           Final synthesized report (15–30k words)
├── refs.md             Compiled references
├── SUMMARY.md          Metrics and stats
├── full/agents/        Raw research from each agent
├── summaries/agents/   Condensed summaries
├── papers/             Downloaded PDFs (with --download-papers)
└── state/              Checkpoints — resume with `deep-report --list`

Machine mode

For driving the CLI from another program (a skill, an agent, CI) use --machine — a silent file-coordinated worker, no prompts, no Rich UI:

deep-report "topic" --machine --name "short-name" [--interactive]

State flows through state/progress.jsonl (tail with tail -F) and state/pending_approval.json. With --interactive, the CLI pauses at approval gates and waits for deep-report --approve --report-dir <dir> --gate <id> --decision approve|reject|stop_early.

License

MIT