verified-deep-research

A deep-research engine that checks its own citations — it verifies every cited claim against its source before the claim is allowed into the report, unlike tools that just cite a URL and hope.

Most "deep research" tools fan out web searches and drop a link next to each sentence. Nobody checks that the link is real, that the quoted text is actually on the page, or that the page actually supports the sentence. This one does: every cited claim passes a three-stage gate (the source resolves → the cited span is on the page → the page entails the claim) before it reaches the report. Claims that fail are re-sourced or weakened to what a source actually supports — never silently kept.

It runs as a Claude Code skill (auto-discovered once installed) and as a headless CLI. Bring your own Anthropic API key.

Install

npx verified-deep-research

This copies the skill into ~/.claude/skills/verified-deep-research/ (idempotent — re-run to update). Then install the Python dependencies it prints:

pip install -r ~/.claude/skills/verified-deep-research/requirements.txt   # anthropic, rapidfuzz

Requires Python 3.10+ and Node 16.7+.

Set your key (BYOK)

The engine reads ANTHROPIC_API_KEY from the environment — it never stores or parses a key file.

export ANTHROPIC_API_KEY=sk-ant-...

A key is required for verify ON (the default). Verify OFF still needs a key for the search + writing steps but makes zero verification calls.

Run it (headless)

python ~/.claude/skills/verified-deep-research/engine.py "<your question>" report.md [--verify on|off] [--cache-dir DIR]

Example:

python ~/.claude/skills/verified-deep-research/engine.py \
  "What is the current state of solid-state battery commercialization in 2026?" \
  report.md

Writes report.md plus report.md.stats.json (cost, wall-clock, verdict counts, citation-alignment numbers). In Claude Code, just ask for "verified deep research on X" and the skill triggers.

--verify on vs --verify off — the speed/cost tradeoff

| | --verify on (default) | --verify off | |---|---|---| | What you get | a verified report — every cited claim passed the gate | a fast classic deep-research report | | Speed | slower (minutes — each claim is fetched and judged) | fast (the gate and repair are skipped) | | Cost | costs credits (per-claim judging + repair/coverage re-verify) | free of verify spend (only search + writing) | | Citations | annotated verify: PASS; failures repaired or weakened | plain, and the report carries a prominent UNVERIFIED banner | | Key | needed | needed for search/writing; no key needed for the verify step |

An OFF report is visibly unverified by design — top banner, verdict-free citations — so it can never be mistaken for a verified one. Use OFF for cheap drafts; use ON when the citations have to hold.

Honest limitations

• A PASS certifies grounding, not source quality. It means the citation is real and the page supports the claim — it does not rank how authoritative the source is. A correctly-cited low-authority blog still reads PASS. Source-authority ranking is a separate layer that does not exist yet.
• Runs take minutes. A verify-ON run fetches and judges every claim serially; expect several minutes and real API spend per question.
• Agent failures happen at scale. The pipeline fans out many web-search and verification calls; individual agents can time out, hit rate limits, or return thin results. The engine degrades gracefully (skips, flags gaps, keeps going) rather than producing a perfect run every time — treat the report as a strong draft with its grounding checked, not an oracle.

License

MIT — see LICENSE.