Deepdive

Your machine. Your LLM subscription. Your search backend. Your cited report.A local research agent: ask a question, it plans sub-queries, searches the web, reads the pages in a real browser, iterates with a critic loop until the answer stops having gaps, and writes you a cited markdown report. Nothing leaves your laptop except the searches you run and the URLs the planner picked to read. Every LLM call routes through dario (or any Anthropic-compat endpoint), so the 30-to-60 calls a deep query burns bill against the Claude Max subscription you're already paying for — not a hosted tool stacking its margin on top of Anthropic's API pricing.

Zero hosted dependencies. MIT. Independent, unofficial, third-party — see DISCLAIMER.md.

What you keep

Every hosted research tool — Perplexity, OpenAI Deep Research, Gemini Deep Research — solves a real problem: one question → plan → search → read → cited answer. They also quietly take four decisions away from you:

Your data. The question, the sub-queries the planner invents, every URL the agent chose to read — all of it goes to the vendor's servers. Often to their analytics pipeline. Sometimes to their ad-targeting pipeline. With deepdive, none of that exists. The planner runs in your Node process. The searches hit whichever backend you point at (DuckDuckGo by default, zero keys required; SearXNG, Brave, Tavily, or Exa if you'd rather). The only outbound connections from your machine are: your chosen LLM endpoint, your chosen search endpoint, and the specific URLs the planner decided to read. No telemetry, no analytics, no data retention. Inspectable: lsof -i during a run.

Your model. Hosted tools pick for you — Perplexity routes through their own blend, OpenAI uses GPT-5, Gemini uses 2.5 Pro. deepdive runs whatever model your endpoint exposes. Default is claude-sonnet-4-6 for a good quality/cost balance; switch to claude-opus-4-8 for reasoning-heavy questions; point --base-url at a LiteLLM or vLLM instance and run a local model. Same one-line flag either way.

Your search backend. Hosted tools use their own search index and won't tell you its exact shape. deepdive swaps between DuckDuckGo HTML (default, no key), self-hosted SearXNG, Brave Search API, Tavily, or Exa with one flag. Adding a new adapter is ~30 lines of TypeScript.

Your depth. Hosted tools cap how far the agent will dig because unbounded research eats their unit economics. deepdive's --deep flag keeps iterating with a critic LLM — review draft → name the gaps → search for them → re-synthesize — until the critic says the answer is complete or you hit --deep=N rounds. You decide where the ceiling is.

What you stop paying for

Most people reading this already pay Anthropic for Claude Max ($100–200/mo). A hosted research tool asks for another $20/mo subscription — on top of a subscription you already have — so some vendor's servers can run LLM calls that your Max plan would have covered for free.

Here's the math for one deep query — a question that needs the critic loop to finish well, roughly 50k–200k tokens across planner + synthesis + critique + re-synthesis:

| How you run it | Per-query cost | Per-month cost at 10 queries | Data stays local? | |---|---|---|---| | Per-token API (claude-opus-4-8) | ~$2–$8 | ~$20–$80 | Your infra, your call | | Per-token API (claude-sonnet-4-6) | ~$0.30–$1.20 | ~$3–$12 | Your infra, your call | | Perplexity Pro | Capped depth, fixed tier | $20/mo | ❌ Perplexity + upstream | | OpenAI Deep Research (ChatGPT Plus) | Capped usage, fixed tier | $20/mo | ❌ OpenAI + upstream | | Gemini Deep Research (AI Advanced) | Capped usage, fixed tier | $20/mo | ❌ Google + upstream | | deepdive + dario + Claude Max | $0 per query | $0 (included in Max) | ✅ your machine |

The cost-arbitrage argument is: the deep-research workload is exactly the shape Claude Max was priced for — 50k–200k tokens per question, sustained, bursty. Running it through a second subscription that marks up LLM calls on top of LLM calls is paying twice for something you already bought. dario unlocks the subscription; deepdive is the tool that uses it for this workload.

The nightly report card

Every night at 04:23 UTC, five fixed research questions — one per failure axis found while live-testing the deployed agent — run through a production deepdive runner. Each run's source-trust mix, citation-verification support, confidence, and cost land in a ledger that publishes automatically to this repo's canary-data branch and charts live at sprayberrylabs.com/deepdive-canary — including the nights that fail. A receipt that can't fail is a press release; that page is where these ones would fail in public.

60 seconds

# 1. Start dario (your local LLM router — https://github.com/askalf/dario).
dario proxy                         # http://localhost:3456, routes to Claude Max, OpenAI, etc.

# 2. Install deepdive.
npm install -g @askalf/deepdive
npx playwright install chromium     # first run only, ~300 MB

# 3. Ask.
deepdive "how does claude's rate limiter work" --deep --verbose --out=report.md

--deep turns on the critic loop (2 extra rounds by default). --verbose streams every plan / search / fetch / critique step to stderr so you can watch the agent think. --out writes the cited markdown to a file in addition to stdout.

What the output looks like

A real deepdive run produces a file like this (excerpt):

# how does claude's rate limiter work

Claude's rate limiter uses a two-tier rolling window: a **5-hour bucket**
and a **7-day bucket**, both scoped per OAuth session [1][2]. Requests
are billed against the short-term bucket first; when that window is
exhausted, the `representative-claim` response header switches from
`five_hour` to `seven_day` and Anthropic begins charging against the
longer bucket — still subscription billing, not API overage [3].

Exhausting both buckets triggers `overage` state, at which point per-token
Extra Usage charges apply if the account has enabled them; otherwise the
request gets a 429 [3][4]. The `anthropic-ratelimit-unified-*` response
headers expose the current utilization at request-response time so
clients can pool-balance intelligently [5].

...

## Sources

1. [Anthropic rate-limit headers docs](https://docs.anthropic.com/...) — fetched 2026-04-22
2. [Claude Code /usage command reference](https://code.claude.com/...) — fetched 2026-04-22
3. [Discussion #32 — seven_day claim explainer](https://github.com/...) — fetched 2026-04-22
4. [Anthropic overage billing documentation](https://docs.anthropic.com/...) — fetched 2026-04-22
5. [dario pool-mode implementation notes](https://github.com/...) — fetched 2026-04-22

Citations are numbered and inline. The source table at the end records the exact URL and fetch timestamp for every source, so you can verify any claim the model made.

Cookbook

Five concrete shapes the tool gets used for. Copy, swap the query, run.

Latest benchmark results

deepdive "what are the latest results on the SWE-bench leaderboard" --out=swebench.md

Single-pass run, roughly $0.05–$0.15 in tokens. Surfaces the current top systems with cited result rows and submission dates — no critic loop, since "what's on the leaderboard" is a factual lookup, not a thing that needs arguing about.

How does X work, technically

deepdive "how does claude's prompt caching actually work" --deep --verbose --out=caching.md

Critic loop iterates until the report covers TTL semantics, billing impact, and known gotchas. --verbose prints each round's critic verdict so you can see what's missing. Typical cost $0.50–$2 depending on how many rounds it takes to satisfy the critic.

Best practices for $stack at small scale

deepdive "best practices for running postgres for a single-node side project in 2026" --deep=3 --search=brave --out=pg.md

Three-round critic-bounded report. --search=brave swaps the default DDG adapter for Brave, which tends to return fresher results on fast-moving ecosystem questions. Useful when the default search keeps surfacing pre-2024 blog posts.

Compare A vs B with current data

deepdive "perplexity vs you-com vs gemini deep research — current limits, pricing, and use cases" --deep --strict-cites --out=compare.md

--strict-cites exits non-zero if any claim fails lexical recall verification against its cited source. Good for scripted comparison reports where you'd rather get a hard failure than a confidently-cited hallucination about somebody's pricing tier.

Mix project notes with web research

deepdive "is our retroactive-billing policy compatible with EU consumer law" --include=~/notes/billing,./POLICY.md --deep --out=billing.md

--include blends local files into the source pool; they get the lowest citation IDs and the most prominent position in the prompt. The output cites both file:// paths and URLs, so an internal doc and a regulator's site can sit side by side in the same source table.

The --deep loop

Single-pass mode (no --deep flag) is what other local "research CLI" tools do: plan → search → fetch → synthesize → done. Good enough for simple factual lookups. Not great for "explain how X actually works."

--deep adds a critic:

plan ──▶ search ──▶ fetch ──▶ synthesize ──▶ critic ─┐
                                                      │
                              ◀───── "here's what's missing, try: q4, q5" ──┘
                              │
                              ▼
                          search ──▶ fetch ──▶ synthesize ──▶ critic ──▶ ...

The critic reads its own draft, flags gaps ("the draft didn't source the 429 header format"), and proposes up to three follow-up queries. The loop re-runs with those queries, re-synthesizes from every source gathered so far, and passes to the critic again. When the critic says the draft is complete — or when you hit --deep=N rounds — the loop stops.

Bare --deep = 2 extra rounds. --deep=5 = up to 5. --deep=0 is explicit single-pass.

In a TTY, every round's draft streams as it's written — round 0 lands under the question's H1; subsequent rounds are separated by a --- divider and a ## Round N (deep) header so you can read along as the agent iterates. The final round is whichever one the critic declared done on, or the round you set as the ceiling. The --out file gets only the final markdown answer; the streamed intermediate drafts are visible in the terminal but not persisted there.

Why this is the whole point. The critic loop is the axis hosted tools cap on. Per-query unit economics force them to ship a fixed depth — if they let you run a 5-round loop, some users would and their margins would collapse. On your own subscription, the only cap is the one you set on the command line.

Citation verification

After every synthesis, deepdive checks each [N] citation in the answer against the extracted text of source N. This is a cheap, deterministic, lexical pass — no second LLM call — that catches the dominant failure mode of cited-answer tools: the model writing a confident sentence with a [3] whose source 3 doesn't actually contain the claim.

For each sentence with a citation, the verifier tokenizes the claim into content tokens (lowercased, stop-words dropped, numbers preserved) and scores recall against each cited source's tokens. A multi-cite sentence like "X happened in 2024 [1][3]" is supported only when every cited source clears the threshold — a bogus [3] buried in an otherwise-true sentence is still flagged.

When something fails, deepdive prints a small ## Citation health footer at the end of the answer and surfaces the offending sentences in --verbose. Clean runs stay clean: no footer, no noise. Use --strict-cites in scripts to fail the run with a non-zero exit code.

In --deep mode the verifier runs once per round, not just at the end: when intermediate rounds produce sentences with weak citations, those sentences are forwarded to the critic as top-priority gaps to fill in the next round of search. The critic and verifier close the loop — instead of "find more sources, hope they help," the next round explicitly hunts for authoritative support for the exact sentences that lack it.

What this is not: a semantic judge. Lexical recall flags hallucinated names, numbers, and dates with high precision, but a paraphrased-but-truthful sentence can score below threshold and a topic-aligned-but-incorrect sentence can score above. Treat the report as a sanity check and a reading guide, not a proof of correctness. To dial the strictness, raise --cite-min-recall above the default 0.4; to disable entirely, pass --no-verify-cites.

Source authority

Citation verification answers "does the answer match its cited source?". Source authority answers the orthogonal question "is that source itself trustworthy?" — a confident, fully-cited answer built entirely on content-farm spam scores clean on the former and low here. Shipped in v0.26.0, it's a second source-trust axis, reported separately so neither signal is mistaken for the other.

Scoring is deterministic — no LLM, no extra network call — keyed on a source's domain alone, into four tiers (primary, reputable, unknown, low). It leads with high-precision boosts (official docs, primary sources, .gov/.edu, standards bodies), treats anything unrecognized as unknown rather than penalizing a niche-but-legit source, and keeps the low-trust list a small, curated denylist of observed content farms — precision over recall.

--source-authority= (env DEEPDIVE_SOURCE_AUTHORITY, default prefer) controls how that score is used when ordering candidates into the round's limited fetch slots:

• prefer (default) — stable-sort candidates by authority descending. Nothing is dropped; only the order changes, and search order is preserved within a tier, so authoritative sources win the slots ahead of whatever search happened to rank first.
• strict — additionally drop low-tier (known content-farm) candidates, unless every candidate this round is low, in which case they're kept. That min-keep floor means a niche or recency topic that only surfaces farms still gets sources rather than nothing.
• off — identity. Search order is left untouched.

The same setting also biases search itself: when fanning out across several backends (--search=multi:…), the merged candidate pool is reordered by authority before the result cap, so a primary source a backend ranked low still survives into the pool the keep-stage sees instead of being truncated by a farm that ranked first (strict drops the farms outright, with the same min-keep floor). Single-backend searches are unaffected — there the backend's own ranking is all there is, and the keep-stage reorders what it returns.

Independently of the mode, the run reports an aggregate trust read across the kept sources — high (no low-trust sources and at least half primary/reputable), low (at least half are known farms), or mixed (everything in between). --json carries it as sourceTrust ({ label, counts: { primary, reputable, unknown, low, total } }), each source row carries its own authority tier, and the HTML export (deepdive export --format=html) shows the same trust badge on the report's meta line when there's something to flag.

Measured, not promised: the bench commits its off-vs-prefer boards to [bench/results/](bench/results/). At [v0.27.0](bench/resu

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: askalf
• Source: askalf/deepdive
• License: MIT
• Homepage: https://www.npmjs.com/package/@askalf/deepdive

Install and usage instructions live in the source repository linked above.