Hyperresearch: Claude Code Deep Research Pipeline

Q: How do I install and set up Hyperresearch in my Python and Claude Code environment?

Run pip install hyperresearch && hyperresearch install inside your project, then invoke /hyperresearch in Claude Code. Python 3.11 through 3.13 is required; 3.14 is not supported yet. The README suggests pyenv install 3.13 , uv venv -p 3.13 , or py -3.13 -m venv .venv to get a compatible interpreter.

Q: Can Hyperresearch resume a run that crashed?

Yes. Each run owns an isolated workspace under research/runs/ / with a manifest, and hyperresearch run resume reports the exact next step plus its Skill invocation. Concurrent runs never collide because each workspace is isolated.

What Hyperresearch Actually Does to a Research Prompt

Hyperresearch is an open-source, MIT-licensed Python deep research framework that turns Claude Code into a deep research agent. One prompt goes in, a tier-adaptive 16-step pipeline runs, and an adversarially-audited report comes out, with every fetched source stored in a persistent markdown vault indexed by SQLite. It installs a CLI, an MCP server, and a local web UI on top of that vault. The citation layer gets verified mechanically before anything ships, and the license is MIT.

Why the One-Shot Report Model Broke

Most deep research harnesses work like this. You ask a question, the agent reads a pile of pages, writes a report, and throws everything away. The sources, the quotes, the half-checked claims, all gone. Next session starts from zero.

And the report itself often cannot be verified. A citation points at an abstract. A quote exists nowhere in the corpus. A retracted paper gets cited as if it still stands. The reader has no way to audit any of it, because the working material was discarded.

Hyperresearch attacks that model at both ends. First, the report pipeline is built so claims get checked against what was actually fetched. Second, nothing is thrown away: every source lands in a searchable, versioned vault that the next run consults before fetching anything new.

How the 16-Step Pipeline Works

The entry skill is a thin router. It pins down the canonical research query, then invokes one step skill per phase via Claude Code’s Skill tool. Each step’s procedure loads into context only when that step actually runs. That is the whole trick for long pipelines: nothing sits in context long enough to rot away, so late steps cannot quietly drop their instructions.

The steps, in order of what they do rather than their numbering: decompose the query into atomic items, sweep the corpus wide across multiple perspectives, pair contradictions into ranked clusters, score depth loci, run parallel investigators that commit to positions in interim notes, reconcile those positions, extract expert disagreements, and run a corpus critic that asks what source would overturn the current direction. Then comes drafting: three parallel draft orchestrators on the full tier, a synthesizer that reads all drafts, four adversarial critics in parallel, a targeted gap-fetch wave, and a patcher that applies the findings.

Tiers, Gears, and What Voice the Report Gets

Tiers route per query. Bounded questions take a five-step light path in roughly 30 to 40 minutes. The default full tier runs all 16 steps with adversarial review in about 1.5 to 2.5 hours. Dissertation runs are opt-in only: 300 to 450 sources across 4 to 10 chapters, 25K to 80K words, roughly 4 to 8 hours.

Gears set the scale. The premier profile targets 100 to 130 sources in the width sweep alone, with citation chasing and gap-fill pushing past 250 sources in a single run. The baseline full gear sits at 55 to 80 sources. Custom gears live in .hyperresearch/config.toml and persist per project.

Levers set the register: teach, survey, analyze (the default), or advocate, plus a sourcing strategy and an inference-depth dial. They render into shim files that shape the critics too, so an evaluative draft gets evaluated and a survey draft does not get hedges stripped. The cite-checker and the ship gate get no shim at all. Verification never softens by mode.

Scale Lever	What Runs	Typical Time
light tier	Five-step fast path for bounded queries	~30-40 min
full tier (default)	All 16 steps plus cite-check	~1.5-2.5 h
dissertation tier (opt-in)	300-450 sources, 4-10 chapters, 25K-80K words	~4-8 h
premier gear	100-130 source width sweep	~3-5 h
full gear	55-80 source baseline	Definition varies by run

Patch, Never Regenerate

Here is the principle that carries the most weight. After the synthesizer produces the report, the only modifications allowed are surgical Edit hunks. The patcher and the polish auditor are tool-locked to [Read, Edit] at the Claude Code allowlist level, so they physically cannot write a new draft. Per-hunk caps make a quiet rewrite mechanically impossible. Critic findings that do not fit a small hunk escalate as structural issues instead of getting absorbed.

The second principle holds the whole thing together: the verbatim user prompt is gospel. It gets persisted to research/runs/<vault_tag>/query.md once, and every subsequent step and spawned subagent re-reads it. Wrapper requirements (save paths, citation format, terminal sections) are a separate contract.

Endless dark library vault where aged pages spiral upward toward a glowing golden network of threads and orbs of…

Every citation is verified before the report ships. Hallucinated quotes and unacknowledged retractions are hard blocks at the gate.Hyperresearch README

The Verification Battery Before Anything Ships

The ship gate runs four mechanical checks. Quote-integrity blocks any quoted span that does not exist verbatim in a vault note. Retracted-citations blocks citing a retracted source without acknowledging the retraction, and a sweep re-checks every cited DOI fresh at ship time, so a retraction published yesterday gets caught today. Numeric-consistency flags numbers that cannot be traced to evidence. The cite-check step audits sampled citation-sentence bindings with a skeptical model pass, followed by a second surgical patch pass.

Fetched web text is treated as hostile input throughout. Every body is served wrapped in <untrusted-source> delimiters with a treat-as-data preamble, on both note show and search. A page telling the agent to ignore its instructions gets read as content, not as a command. Forged fence tags inside a fetched body are neutralized and left visible for forensics.

The Persistent Vault Is the Compounding Part

Markdown is truth, SQLite is cache. Notes live as plain markdown with YAML frontmatter in research/notes/. The SQLite index is fully rebuildable: delete it and hyperresearch sync reconstructs it from markdown. Open the vault in any editor, version it in git. You do not need the tool installed to read your own research.

On top of that base: full-text search, optional semantic search with pluggable embedding providers, hub and backlink graph queries, and provenance breadcrumbs. Every fetched source carries a --suggested-by link back to whatever surfaced it, forming a rooted tree that a lint rule can audit. Crashed multi-hour runs resume at the exact step where they died, and run init --budget 50 caps estimated spend, blocking the run at the cap instead of letting it balloon.

Source Ranking and Independence Audits

Sources accumulate a composite quality score built from source-type tier, fetch-time utility, citation authority from OpenAlex and Semantic Scholar (including retraction flags, floored to near-zero), and PageRank centrality over the link graph. An independence audit clusters derivative copies, so five reprints of one press release argue with the weight of one source. Syndication does not count as consensus.

Use the Vault Outside Claude Code

An MCP server (pip install hyperresearch[mcp]) speaks stdio, so Claude Desktop, Cursor, or anything else that speaks MCP can work the same vault through thirteen tools. A local web UI (hyperresearch serve --open) starts a stdlib HTTP server on port 8080 with note browsing, tag pages, search, and an interactive link graph, no build step, no JavaScript dependencies. Export, import, and git-aware tooling sit on top of the same plain directory.

Academic Open-Access Recovery: Read Before You Cite

A paywalled paper normally enters a vault as a roughly 1,500-character abstract that the report then cites as though the paper had been read. Hyperresearch closes that gap. When a fetch lands a thin page carrying a DOI, it asks Unpaywall and Europe PMC for a legal open-access copy and stores that full text instead, even when the publisher blocks the fetch outright.

The substitution is disclosed in four places: a banner at the top of the note body, frontmatter fields (oa_url, oa_source, oa_version, oa_license, oa_recovery_kind), an oa block in JSON output, and a line in fetch output. The same lookup rescues sources that returned nothing at all (a 403, a login wall, a bot wall), and those notes are marked with nothing_from_source: true. Recovery never fails a fetch and never lowers quality: a candidate must be longer than what you had and clear a minimum full-text threshold, otherwise you keep the abstract.

Two limits matter. Rescue needs a DOI in the URL itself or in a wall page’s meta tag, and version preferences matter: if what came back is an accepted manuscript rather than the published version, check direct quotations against the published paper. Out of the box, the required Unpaywall contact email is empty, so only Europe PMC runs until you set a real address under [scholar] in the config.

The Benchmark Claim, With Its Caveats Attached

The README states that the pipeline currently leads the DeepResearch-Bench RACE leaderboard, benchmarked internally, ahead of systems the banner names as Grep Deep Research, Cellcog Max, nvidia-aiq, Gemini Deep Research, and OpenAI Deep Research. The README’s own caption under that chart describes it as a forward-looking projection from a stratified pilot against a leaderboard snapshot, and states that third-party validation is pending. Treat the ranking as what its own documentation calls it: an internal, unvalidated result.

Macro view of a knowledge network spread like mycelium over dark paper, with silver filaments linking tiny documents,…

For context on the benchmark itself, the DeepResearch Bench paper describes 100 PhD-level research tasks across 22 fields, with Gemini-2.5-Pro Deep Research scoring 48.88 overall, Perplexity Deep Research leading citation accuracy at 90.24%, and OpenAI Deep Research leading instruction-following at 49.27. Those public leaderboard figures and the internal projection are different measurements: the project claims the lead, and the project’s own documentation flags the claim as pending outside validation.

Installation and Setup

Requirements are Python 3.11 to 3.13 (3.14 is not yet supported) and Claude Code. Install per project:

cd your-project
pip install hyperresearch && hyperresearch install

Then /hyperresearch <anything> inside Claude Code. A global install (hyperresearch install --global) makes the command reachable from every session, at the cost of about 15 lines in every session’s system reminder. Per-project install keeps unrelated sessions clean. A third-party skill fiche at thekb.eu reports that installation deploys 20 Claude Code skills alongside the CLI, MCP server, and web UI.

Authenticated Crawling and the Browser Lane

When headless crawling hits a login wall or bot wall mid-run, the URL queues as an escalation instead of dying. If the Claude-in-Chrome extension is present, a browser-fetcher agent drains the queue by driving the user’s real, logged-in Chrome. LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible browser to avoid session kills. The hard boundary: CAPTCHAs, 2FA, and logins are never solved automatically; they are consolidated into one message and handed to the user.

Where Hyperresearch Stops

It does not replace judgment about which sources matter. The agent picks, the user steers.
It cannot fetch what sits behind a paywall the user has not logged into. Open-access recovery finds a legal free copy when one exists; when none exists, the abstract or nothing comes back, and the note says so.
It runs on Anthropic models via the subagent roster, with per-agent assignments configurable per profile. Usage scales with tier, gear, and corpus size.
The lint gate catches structural failures (missing scaffold, broken provenance, unresolved critical findings). It cannot guarantee factual accuracy; that stays a human call.

Where This Leaves Deep Research Tooling

Hyperresearch is a young project with a clear architectural position: research as an auditable, patch-only, stateful process rather than a one-shot generation. The benchmark claim rests on internal numbers its own README qualifies, the factual-accuracy burden stays with the user by the project’s own admission, and the whole thing runs on Anthropic models. What it demonstrably does, from its own documentation, is enforce things most harnesses only promise: verbatim quote checks, retraction sweeps at ship time, untrusted-content fencing, and a vault that outlives the session. For teams running long research workflows in Claude Code, that enforcement layer, not the leaderboard claim, is the part worth testing first.

📊 What Research Teams Should Take From This

Audit trail first: Every citation binding, quote, and DOI status is checked mechanically before a report ships, so verification is structural, not aspirational.
The vault compounds: Markdown-plus-SQLite storage means each session reuses prior sources before fetching new ones, and the plain-text format avoids lock-in.
Scale is configurable: Light queries take a five-step path; opt-in dissertation runs handle 300 to 450 sources across 4 to 10 chapters, with spend caps to keep runs bounded.
Benchmark claims carry caveats: The lead over Gemini and OpenAI deep research systems is internally benchmarked and explicitly flagged by the project as pending third-party validation.
Boundaries are stated plainly: Factual accuracy remains the user’s responsibility, paywalls without a legal open copy stay closed, and the whole pipeline depends on Anthropic models.

Additional Resources

This article includes content created with AI.