Hyperresearch: Making Claude Code Verify Citations and Keep a Research Vault

Hyperresearch is an open-source Python package that tries to fix this. It makes Claude Code behave like a deep research agent: a 16-step pipeline, a lasting vault holding everything it reads, and a set of verification checks that stop a report from shipping when its citations fall apart. The repository is at https://github.com/jordan-gibbs/hyperresearch, and you can pull the package from PyPI. Below you'll find how to run it, with the two configuration choices that make a first run either useful or a letdown.

Three habits it avoids

Three design decisions do most of the work, and each answers a failure you'll recognize from other research agents. They also explain what the wall-clock time buys you.

Repair beats regeneration. After the report is drafted, the agents that touch it are tool-locked to read and edit permissions at the Claude Code allowlist level. The patcher and the polish auditor can't physically write a new draft. Ask an ordinary model to regenerate a 20,000-word document after a critique and you've handed it thousands of chances to change or drop an established fact without anyone noticing. Here, a critic's finding either fits a small surgical edit or escalates as a structural failure. The document can't quietly reshape itself.

Repetition isn't corroboration. If one press release is reprinted across fifty outlets, an uncalibrated agent sees overwhelming consensus. To counter that, an independence audit groups near-duplicate copies by how similar their content is, then divides the weight among the group. Five reprints of a single release end up carrying the weight of one source.

The original question stays pinned. Your exact prompt is written once to a query.md file, and every later step and spawned subagent re-reads it. Multi-agent pipelines drift, and by step 9 the topic can have turned into a simpler cousin of what you asked. Pinning the text and rereading it is a dumb fix that works.

The vault may be the feature that pays off most in the long run. Each page, PDF and working note goes into a searchable store of markdown files plus SQLite inside your project folder. A later run in the same folder looks through what's already there before downloading anything, so the research builds up instead of vanishing.

Installing it without a letdown

Install takes two commands, run inside the project directory where the vault should live:

cd your-project
pip install hyperresearch && hyperresearch install

After that, type /hyperresearch <your question> in Claude Code. Python 3.11 to 3.13 is supported. If you're on 3.14, which isn't supported yet, create a 3.13 environment first with pyenv install 3.13 or uv venv -p 3.13.

The docs mention the next point once and most people skim it. The default web provider is builtin, a plain HTTP fetch with no search at all. It has zero extra dependencies and it isn't what the pipeline was tuned for. If a default run leaves the corpus feeling thin, that's the reason.

The fix is the crawl4ai extra:

pip install "hyperresearch[crawl4ai]"

Then select it in .hyperresearch/config.toml:

[web]
provider = "crawl4ai"

That switches fetching to a headless browser with stealth handling, and it brings PDF text extraction plus the browser escalation lane. Exa and Tavily are supported if you've got keys. Parallel requires no account, but it only searches, and bulk fetches fall back to one URL at a time, so it works best as an add-on.

One more install-time choice. A per-project install keeps unrelated Claude Code sessions clean. A global one (hyperresearch install --global) makes the command available everywhere, at the cost of about fifteen lines in every session's system reminder. Start per-project.

Pick a tier before burning three hours

Every run lands in one of three tiers, picked by step 1, which classifies the query without asking you.

• light runs five of the sixteen steps in about 30 to 40 minutes, and suits bounded factual questions, surveys and comparisons.
• full is the default and runs everything: adversarial critics, cite-checking, the lot. Expect about 1.5 to 2.5 hours.
• dissertation happens only when the prompt asks for it. It organizes the work into 4 to 10 chapters, draws on 300 to 450 sources and produces 25,000 to 80,000 words, taking roughly 4 to 8 hours.

Skip full when a good search plus twenty minutes of reading would do. The classifier is reasonable, but the wording of your prompt nudges it, and a request for a "comprehensive analysis" can cost two hours you didn't need to spend.

Register is the second lever, and it's inferred from the verb in your prompt. "Teach me X" gives a teaching explainer. "What does the field around X look like" gives a map without a verdict. The default, analyze, builds an evaluative argument, and advocate defends a single thesis you name. State the register outright and your instruction wins over the guess.

What makes this work is that the critics follow the register instead of working against it. Under survey, the dialectic critic objects to unfair treatment of competing views and doesn't push for a verdict, and the polish auditor leaves your hedges alone. Under advocate the checks get stricter. The cite-checker and the ship gate never bend, and that's correct: verification shouldn't loosen because you wanted a gentler tone.

Size is controlled separately from voice, through profiles that set source targets and depth budgets:

hyperresearch profile list           # what's available, what's active
hyperresearch profile use premier    # 100-130 sources, doubled depth budget
hyperresearch profile use full       # back to the 55-80 baseline

Cap spending before a long run, too:

hyperresearch run init --budget 50

Crossing the cap blocks the run instead of letting it balloon. It limits estimated API-equivalent spend and isn't a literal bill, so use it for the first few runs while you learn what a premier run costs.

The setting that changes source quality

If a topic has a genuine research literature, query scholarly databases before the open web. A web search brings back people talking about the work, while a scholarly search brings back the work.

hpr scholar search "GLP-1 cardiovascular outcomes" -j
hpr scholar sources    # what's wired up, what each one covers

A single query reaches seven sources right now. Bibliographic and open-access coverage comes from Crossref, OpenAlex, CORE and DOAB. Beyond papers, it also searches registered studies in ClinicalTrials.gov, corporate filings in SEC EDGAR and economic series from FRED. Results merge by DOI, falling back to normalized titles. The README counts eight because RePEc is listed too, though its API can't search. The merged list tags each hit by kind, so trials that never became papers, SEC filings and Fed data aren't confused with journal articles.

Now the setting itself, a real contact email:

export HYPERRESEARCH_CONTACT_EMAIL="you@example.com"

This one value has two effects. It moves you into the polite pools at OpenAlex and Crossref, where rate limits are much looser than for anonymous callers. It's also demanded by the terms of Unpaywall, the first service tried when the pipeline hunts for open-access copies.

With the email blank, only Europe PMC is used, and that covers biomedicine and nothing outside its open-access subset. With it set, a paywall sends the agent to Unpaywall first, with Europe PMC and CORE queued behind it, searching for a legal free copy whose full text replaces the abstract in the note. That decides whether your vault ends up full of 1,500-character stubs or actual papers.

Put the same value under [scholar] in the config:

[scholar]
oa_recovery = true
contact_email = "you@example.com"
oa_min_full_text_chars = 6000
oa_prefer_published = true

Note oa_prefer_published, which does quiet work here. When no published copy is open, Unpaywall may return an accepted manuscript or a submitted preprint, and neither equals the version of record.

Reading the output as someone accountable for it

When open-access recovery kicks in, a note's source: field still shows the URL you asked for, even though the body may have come from a different place. The tool flags this in four spots: a banner at the head of the note, the frontmatter fields oa_url, oa_source, oa_version and oa_license, a JSON oa block from hpr note show <id> --json that includes body_is_not_from_source: true, and a mention in the fetch output itself.

Check oa_version before quoting anything. If it reads acceptedVersion or submittedVersion, verify the quote against the published paper.

There's a harder case. A source that can't be read at all, say because of a 403 or a login wall, goes through the same lookup, and the whole note is built from the open-access copy. Such notes are labeled oa_recovery_kind: rescued and nothing_from_source: true, and a banner admits that the original URL was never opened. Believe it: title, authors and body all come from the replacement. If you'd rather have no note than one assembled from a stand-in, set oa_rescue_blocked = false.

Before shipping, the verification battery runs. A quoted span must appear word for word in some vault note, so an invented quote is a hard stop. A retracted source cited without mention of the retraction is a hard error too, and the retraction sweep rechecks every cited DOI right at ship time, not as it stood when the source was first fetched. Figures with no evidence behind them are flagged.

hyperresearch run verify <tag> -j   # headings, length, citation density, cite-check resolution
hyperresearch run status -j         # step status, spend, escalation queue depth
hyperresearch run resume -j         # crashed runs pick up at the exact step

The final command is a lifesaver: if a run fails at step 12, it picks up again at step 12.

Working with the vault afterward

The report is the output, and the vault is the asset.

hyperresearch search "ion-trap gate fidelity" -j
hyperresearch search "quantum" --include-body -j
hyperresearch graph hubs -j          # most-connected notes
hyperresearch sources independence -j # syndication clusters
hyperresearch lint -j                # broken links, missing tags

Markdown is the source of truth, and SQLite only serves as a cache you can rebuild. If the database is lost, hyperresearch sync regenerates the index from the files on disk. Keep the folder in git and open it in any editor. Your research stays readable without the tool, and that portability counts for more than any one feature.

It runs beyond Claude Code as well. hyperresearch serve --open launches a local web UI on port 8080, and after pip install hyperresearch[mcp], the command hyperresearch mcp offers thirteen tools over stdio, which lets Cursor or Claude Desktop query the same vault.

Limits, and one claim to hold loosely

Fetches that get blocked are queued as escalations, not silently lost. Run hyperresearch setup once and sign in to your sites. If the Claude-in-Chrome extension is installed, a browser-fetcher agent works through that queue using your real logged-in Chrome, getting past paywalls you've paid for. CAPTCHAs, 2FA and logins are never handled automatically, and you get them together in a single message.

The lint gate catches structural failures such as missing scaffolds, broken provenance chains and unresolved critical findings. Factual accuracy is outside what it can promise, a limit the README states openly. Source selection stays with the agent, so steering stays with you.

Then there's the leaderboard claim. The repo says it ranks first in the RACE category of DeepResearch-Bench, though the caption under the chart is candid about it: a forward-looking projection from a stratified pilot, benchmarked in-house, awaiting third-party validation. Publishing that is reasonable, but repeating it as settled fact isn't. Your own runs are the real judge.

Also note how fast it moves. The first PyPI release dates from April 2026, and mid-September 2026 brought 0.11.1 after seventeen releases. Software below 1.0 that churns this quickly will have shifted by the time you read this, so compare any flag mentioned here with the README. It's MIT licensed.

A first run you can actually judge

Don't test it on a subject that's new to you, because you won't notice errors. Choose something you know well enough to catch mistakes, with solid literature below and a heap of rehashed commentary above. That combination exposes the two weaknesses you can't see from the report text alone:

/hyperresearch Survey the evidence on whether remote work changes
software team productivity. Separate individual output from team-level
coordination costs, and distinguish measured studies from company
self-reports. Survey the landscape; don't argue for a position.

The wording is doing real work. "Survey" selects the register, so the output maps the field without issuing a verdict. The two requested separations turn into atomic checklist items in step 1, and the instruction critic later holds the draft to them. The final sentence overrides the register guess so it doesn't depend on the verb alone.

Use light for the first attempt, and skip judging the prose. Open five notes in the vault and answer four questions:

1. Were the actual studies retrieved, or just articles describing them?
2. Which notes contain full text, and which only a 1,500-character abstract? For anything rescued, look at oa_version and nothing_from_source.
3. Take three claims from the report and confirm that the cited note really supports each.
4. Execute hyperresearch sources independence -j. Did syndicated coverage fold into clusters, or does a lone press release still count five times?

If those answers match what you'd have concluded by doing the work yourself, longer runs are worth your afternoon. The test applies to any research agent. Most just don't keep the notes that let you run it.

Begin at the repo with a per-project install, the crawl4ai extra and your contact email, then spend forty minutes on a light run.