hyperresearch: a tiered 16-step deep research harness for Claude Code

Key takeaways

1. Nature. a deep research harness shipped as a package of 20 Claude Code skills + Python CLI + MCP server + local web UI. pip install hyperresearch && hyperresearch install, then /hyperresearch <topic>. MIT, Python 3.11-3.13.
2. Key framing. the entry skill is a router with no procedure, each step living in its own skill loaded fresh at invocation. ### The architecture lesson, with its documented failure mode > « V7 was one 1200-line skill that got compacted away by the time Layer 4 needed its triple-draft procedure. The orchestrator forgot the procedure, wrote a single draft, and produced a flat-scoring report. V8 fixes this at the source: each step's procedure is loaded into context only at the moment it's needed, fresh, with no eviction risk. » A long pipeline does not lose its steps to the model forgetting but to context eviction, and the fix is structural. Same discipline as the persistent context that carries the index rather than the content in [[lassiege-usine-logicielle-heure-ia-2026-07-28]], discovered independently on different ground. ### Tool lockdown as a guarantee 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 », with per-hunk caps making « just rewrite it » mechanically impossible. The agent is not asked not to rewrite — the tool is taken away. Corollary: a critique finding that does not fit within a small touch-up escalates to a structural problem instead of triggering a rewrite. ### The sixteen steps, in three blocks | Block | Steps | |---|---| | Framing | 1 decomposition + coverage matrix + tier classification; 1.5 chapter partitioning | | Corpus and analysis | 2 breadth sweep; 3 contradiction graph; 4 loci analysis; 5 parallel deep investigations; 6 inter-loci reconciliation; 7 tensions between sources; 8 corpus critique (« what source would overturn this? ») + targeted gap-filling; 9 evidence digest | | Writing and audit | 10 triple drafting by angle; 11 synthesis; 12 four parallel adversarial critiques; 13 post-critique gap-filling; 14 surgical patcher; 14.5 citation verification; 15 polish; 16 readability audit | ### Three scaling levers not to confuse | Lever | Decides | |---|---| | Tiers (tier) | which steps run, routed per query | | Gears (scale profiles) | how much — source targets, depth budgets, length; survive reinstalls, take effect on the next run, never mid-run | | Levers (register, domain_notes, inference_depth) | which voice — teach / survey / analyze / advocate | Levers land as shims injected into subagent prompts, « so the critics move with the register instead of undoing it ». But: « The cite-checker and the ship gate receive no shim at all. Verification never softens by mode. » Verification is the one stage exempt from style. ### The three mechanical gates before shipping 1. quote-integrity — every portion quoted must exist verbatim in a vault note; « hallucinated quotes cannot ship ». 2. retracted-citations — citing a retracted source without flagging it is blocking, with a sweep refreshed at shipping time on every cited DOI, including sources reused from older runs: « a retraction published yesterday is caught today ». 3. numeric-consistency — numbers not traceable to a piece of evidence are flagged. Added to this is cite-check: a skeptical LLM samples whether the cited source actually supports the sentence it backs. ### The independence audit Syndicated and derivative copies are grouped, so that « five reprints of one press release argue with the weight of one source ». The number of agreeing sources stops being an argument once they all descend from the same press release — relevant to any tech-watch practice. Composite, persistent quality score: source type, usefulness observed on reading, citation authority (OpenAlex / Semantic Scholar with retraction flags), PageRank over the internal graph. Retracted sources floored to zero: « Quality is persistent, not vibes. » ### The defense against prompt injection « Fetched text is data, never instructions. » Every body fetched from the web is served inside an <untrusted-source url="..."> fence with a treat-as-data preamble, on both paths that serve bodies (note show and search). Details that show the threat was thought through:
3. notes written by subagents pass through without a fence — trust boundary by provenance, not by content;
4. forged fence tags inside a fetched body are neutralized but left visible for forensic analysis;
5. the url attribute is escaped and its control characters stripped;
6. in search, wrapping happens after truncation to the token budget, « so the closing fence can never be severed »;
7. URLs resolved via third-party APIs are verified (scheme, embedded credentials, publicly routable resolution) — SSRF defense;
8. the fetcher, investigator, and writer prompts forbid laundering directives from a fenced page into trusted output. ### Epistemic hygiene on closed sources A paywalled article would normally enter the vault as an abstract of about 1,500 characters, which the report would then cite « as though it had been read ». hyperresearch queries Unpaywall and Europe PMC for a legal open-access copy and stores that text instead, disclosing the substitution in four places (banner, oa_ frontmatter, body_is_not_from_source: true JSON block, CLI output). A third state is distinguished: the « rescued » note, when the source could not be read at all — nothing_from_source: true, with a banner stating that the URL was never read. The system thus distinguishes « I read this », « I read a substitute », and « I never read the source », and carries that distinction into the artifact. Caveat: Unpaywall can return an accepted manuscript or a submitted preprint, to be checked before direct citation. ### The vault « Markdown is truth, SQLite is cache » — a fully rebuildable index (hyperresearch sync), markdown notes + YAML frontmatter readable without the tool, git-versionable, a curated lifecycle (draft → review → evergreen or stale → deprecated → archive) « that keeps a vault from becoming a dump of half-read pages », provenance via --suggested-by with a lint rule detecting disconnected components, hubs, and backlinks. This is the architecture of this tech-watch corpus, discovered independently. What hyperresearch adds on top: per-source quality score, independence audit, retraction sweep, optional semantic search, explicit lifecycle status. A lead worth borrowing for scripts/. ### Run resume and budget Each run has an isolated workspace (research/runs/<tag>/) and a manifest serving as « durable memory »: a crashed run resumes exactly at the dead step (run resume). run init --budget 50 blocks the run when the cap is crossed « rather than letting it quietly balloon »*. ### Reservations
9. The ranking claim does not hold up. The README states « currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally) » with a chart placing it ahead of Gemini and OpenAI Deep Research; the note below the chart says « Forward-looking projection from a stratified pilot… Third party validation is pending. » A projection from a self-administered pilot is not a ranking. Cite the setup, never the ranking.
10. Anthropic dependency. « It runs on Anthropic models via the subagent roster » — Opus for critics, synthesizer, and patcher, Sonnet for fetchers. A Codex port is desired but not done.
11. Cost not quantified. premier targets 100-130 sources and ~3-5 h, dissertation 300-450 sources and 4-8 h; the budget cap is expressed in API-equivalent spend, not observed cost.
12. Limit acknowledged by the author. « The lint gate catches structural failures… It cannot guarantee factual accuracy, that's still your call. » Structural verification is not factual accuracy.
13. Hard boundary. « CAPTCHAs, 2FA, and logins are never solved automatically » — consolidated and handed back to the human.
14. Dependency surface. 20 skills, 16 subagents, and a CLI that drives an authenticated browser, on a repo less than four months old.