hyperresearch: tiered skill harness for Claude Code deep research

Key takeaways

1. Nature. deep research harness shipped as a package of 20 Claude Code skills + Python CLI + MCP server + local web UI. Install via pip install hyperresearch && hyperresearch install, then /hyperresearch <topic>. MIT, Python 3.11-3.13.
2. ⭐⭐ The architecture lesson, with its documented failure mode. — the most transferable part, independent of the tool: the entry skill is a router containing no procedure at all, only the invocation order. Textual justification: « 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 doesn't lose its steps because the model forgets, but because context gets evicted, and the fix is structural: one skill per step, loaded on invocation. This is exactly the discipline of [[lassiege-usine-logicielle-heure-ia-2026-07-28]] ("the permanent context carries the index, not the content") discovered independently on different ground. A convergence worth noting.
3. ⭐ Tool-locking as a physical 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 that make « just rewrite it » mechanically impossible. → The agent isn't told not to rewrite — the write tool is taken away from it. Same family as « a hook or a test is enforced every time » ([[lassiege-usine-logicielle-heure-ia-2026-07-28]]) and the constraint ring in [[sfeir-code-review-anneau-contraintes-2026-07-30]]: mechanical impossibility beats instruction. Operational corollary: a critique finding that doesn't fit a small touch-up escalates into a structural problem instead of triggering a rewrite.
4. The sixteen steps, in three blocks. (the structure matters more than the detail): framing (1 decomposition + coverage matrix + tier classification, 1.5 chapter partitioning) → corpus and analysis (2 breadth scan, 3 contradiction graph, 4 loci analysis, 5 parallel depth investigations, 6 cross-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).
5. Three scaling levers not to be confused. — a clean, reusable distinction: tiers route by query and decide which steps run; gears (scale profiles) decide how much — source targets, depth budgets, length — and « survive reinstalls », taking effect on the next run, never mid-run; levers (register, domain_notes, inference_depth) decide which voice comes out — teach / survey / analyze / advocate. ⭐ Fine detail: levers land in shims injected into subagent prompts, « so the critics move with the register instead of undoing it » — in survey register, the dialectic critic flags unfair representation rather than lack of engagement. 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. An excellent design rule.
6. ⭐ The three mechanical gates before shipping. (the best part of the setup, directly transferable to any documentary corpus): 1. quote-integrity — any portion quoted between quotation marks must exist verbatim in a vault note; « hallucinated quotes cannot ship ». 2. retracted-citations — citing a retracted source without flagging it is a blocking error, with a retraction scan 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 evidence are flagged. Plus cite-check: a skeptical LLM samples whether the cited source actually supports the sentence it backs.
7. ⭐ The independence audit — the most immediately stealable idea. syndicated and derivative copies are grouped, so that « five reprints of one press release argue with the weight of one source ». The count of agreeing sources stops being an argument once they all descend from the same press release. Relevant to any tech-watch practice: reprint redundancy disguises itself as consensus.
8. Persistent composite quality score. source type + observed usefulness on reading + citation authority (OpenAlex / Semantic Scholar, with retraction indicators) + PageRank on the vault's internal graph. Retracted sources are floored to zero. « Quality is persistent, not vibes. »
9. ⭐⭐ The prompt-injection defense — the most serious seen in an open harness. « Fetched text is data, never instructions. » Any 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 showing the threat was taken seriously:
10. notes written by the pipeline's own subagents pass through without a fence → trust boundary by provenance, not by content;
11. forged. closing fences found in a fetched body are neutralized but left visible for forensic analysis;
12. the url attribute is escaped and its control characters stripped;
13. in search, wrapping happens after truncation to the token budget, « so the closing fence can never be severed » — the detail that gives away that the bypass was actually hunted for;
14. URLs resolved via third-party APIs are checked (scheme, embedded credentials, publicly routable resolution) → SSRF defense;
15. fetcher, investigator, and writer prompts carry a clause forbidding laundering directives from a fenced page into trusted output. → Compare with « a security boundary that relies on a prompt instruction is not a boundary » ([[sfeir-anthropic-sdlc-ai-native-securise-2026-07-26]]): here the fence is mechanical and the instruction merely backs it up. Same logic of treating observed content as data as in [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]].
16. ⭐ Epistemic hygiene on paywalled sources — remarkable and rare. a paywalled article would normally enter the vault as a ~1,500-character abstract, 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 in the body, oa_ frontmatter, JSON block body_is_not_from_source: true, CLI output). And crucially, a third state is distinguished: the "rescued" note, when the source could not be read at all — nothing_from_source: true, a banner stating the URL was never read, « the title, the authors, and every word of the body are the open-access copy's »*. Version warning: Unpaywall can return an accepted manuscript or a submitted preprint, to be checked before any direct citation. → The system distinguishes "I read this" from "I read a substitute" from "I never read the source", and carries that distinction into the artifact. Directly transferable to a tech-watch practice.
17. The vault, and its unsettling closeness to this very repo. « Markdown is truth, SQLite is cache » — fully reconstructible index (hyperresearch sync), notes in markdown + YAML frontmatter readable without the tool, versionable in git, exportable/importable, curated lifecycle (draft → review → evergreen or stale → deprecated → archive) « that keeps a vault from becoming a dumping ground of half-read pages », provenance via --suggested-by with a lint rule that detects disconnected components, hubs, backlinks, wikilinks. ⭐ This is the architecture of this very tech-watch corpus, discovered independently: markdown source, generated index as cache, lint gate, doctor, wikilinks. What hyperresearch has on top and this corpus lacks: per-source quality score, independence audit, retraction scanning, optional semantic search, explicit lifecycle status. A serious inspiration path for scripts/.
18. Resume and budget. each run has an isolated space (research/runs/<tag>/) and a manifest that serves as « durable memory » — a crashed run resumes exactly at the dead step (run resume). run init --budget 50 blocks the run once the cap is crossed « rather than letting it quietly balloon ». Concurrent runs don't collide.
19. ⚠️⚠️ The reservation to flag systematically — the benchmark claim. the README states upfront that the tool « currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally) », chart included, placing it ahead of Grep Deep Research, Cellcog Max, nvidia-aiq, Gemini Deep Research, and OpenAI Deep Research. The note beneath the chart says something else: « Forward-looking projection from a stratified pilot against the DeepResearch-Bench leaderboard snapshot. Third party validation is pending. » → A forward-looking, self-administered projection from a stratified pilot, with no third-party validation, is not a ranking. The two statements are not compatible, and it's the one place in the repo where the rigor displayed everywhere else slips. Never cite the ranking; cite the setup.
20. ⚠️ Other limitations, some acknowledged by the author.
21. Anthropic dependency. « It runs on Anthropic models via the subagent roster » — Opus for critics, the synthesizer, and the patcher, Sonnet for fetchers. A Codex port is explicitly welcomed but not done (« If anyone wants to port this to Codex, put up a PR! »).
22. Real cost not quantified in euros. premier targets 100-130 sources at scan-only and ~3-5 h; dissertation targets 300-450 sources and 4-8 h. The budget is capped in "API-equivalent spend," not observed cost.
23. The honest limitation, worth quoting. « The lint gate catches structural failures… It cannot guarantee factual accuracy, that's still your call. » → Structural verification ≠ factual accuracy. The whole setup guarantees that a citation exists, not that it is true.
24. A hard and welcome boundary. « CAPTCHAs, 2FA, and logins are never solved automatically » — escalated and handed back to the human.
25. Dependency surface. 20 skills + 16 subagents + a CLI driving an authenticated browser, on a repo under four months old. The warning from [[lassiege-usine-logicielle-heure-ia-2026-07-28]] fully applies (« any skill, MCP, or code pulled in from outside must be scrutinized »).
26. Meta / to link. the most accomplished instance of the harness engineering from [[osmani-agent-harness-engineering-2026-04-19]]; converges independently with [[lassiege-usine-logicielle-heure-ia-2026-07-28]] on deferred context loading and on the executable beating the instruction; same doctrine of mechanical boundary as [[sfeir-anthropic-sdlc-ai-native-securise-2026-07-26]] and [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]]; kinship in form with the corpus's other skill entries, [[skill-pocock-grill-with-docs-2026-06]] and [[akhouri-adhd-ideation-divergente-parallele-2026-07-20]]; to read alongside [[agent-skills-anthropic-2025-10-16]], [[shihipar-claude-code-lessons-building-skills-2026-06-03]] and [[vincent-superpowers-agentic-skills-framework-github-2026-04-02]] on skill mechanics; the parallel adversarial critique connects to the question raised by [[monperrus-end-of-code-review-agents-supersede-2026-06-11]] about what an automated review can carry.