最强大的深度研究框架

---

**Hyperresearch 将 Claude Code 转变为深度研究 Agent：其目前在 DeepResearch-Bench RACE 排行榜中领先（内部基准测试）。**一条按档位自适应的 16 步流水线接收一个提示词，并产出经过对抗审计、具有完整来源溯源信息的报告。它读取的每一份来源都会进入一个持久、可搜索的 vault，因此每次会话都会比上一次更聪明。

基于针对 DeepResearch-Bench 排行榜快照（https://huggingface.co/spaces/muset-ai/DeepResearch-Bench-Leaderboard）进行的分层试点测试得出的前瞻性预测。尚待第三方验证。

• 单次运行覆盖 250+ 个来源。premier 规模配置仅在广度扫描阶段就以 100—130 个来源为目标；引文追踪和缺口填补抓取的材料数量，超过最终实际进入语料库材料的两倍。

• **报告发布前会验证每一条引文。**一个持怀疑态度的引文检查器会审计每个被引用来源是否确实支持对应句子。虚构引文和未说明的撤稿均会成为发布关卡的硬性拦截条件。

• **联合转载不等于共识。**独立性审计会对衍生副本进行聚类，因此同一篇新闻稿的五次转载，其论据权重也只相当于一个来源。

• **天生具备对抗性。**四名批评 Agent 并行攻击每一份草稿，而工具锁定的修补 Agent 只能实施外科手术式编辑。它从机制上无法重写报告。

• **付费墙后的论文会被阅读，而非仅浏览摘要。**一篇受限论文通常只会以 1,500 个字符的摘要进入 vault，报告却会像已经读过全文一样引用它。Hyperresearch 会向 Unpaywall 和 Europe PMC 索取合法的开放获取版本，并保存全文；即使出版商完全阻止抓取也是如此。每一项替换都会在注释、frontmatter 和 CLI 输出中披露。

• **不会丢弃任何内容。**每个来源都会进入一个可搜索的、由 Markdown 和 SQLite 构成的 vault，供下一次会话在抓取任何新内容前复用。

• **崩溃的运行可以恢复。**每次运行都会保留 manifest；run resume 会从中断时的准确步骤继续执行。

• **可从 30 分钟扩展至一篇论文。**有界查询会自动路由至 5 步快速路径。选择启用论文级运行后，可跨多个章节写出 25K—80K 字，覆盖 300—450 个来源。

  cd your-project pip install hyperresearch && hyperresearch install

随后可在 Claude Code 中使用 /hyperresearch <anything>。

Python 3.11–3.13。（暂不支持 3.14。请使用 pyenv install 3.13、uv venv -p 3.13 或 py -3.13 -m venv .venv。）

高级用户：hyperresearch install --global 可让 /hyperresearch 在任何位置的每个 Claude Code 会话中可用，代价是在每个会话的系统提醒中增加约 15 行内容。按项目安装（如上）则可保持无关的 CC 会话整洁。

---

16 步研究流水线

入口 skill 是一个轻量路由器。它先确定规范化研究查询，然后通过 Claude Code 的 Skill 工具，在每个阶段调用一个步骤 skill。每一步的流程仅会在实际运行该步骤时加载进上下文。这正是防止长流水线随着上下文衰减而悄然漏掉步骤的机制。

编号	步骤	功能	档位
1	分解	规范化查询 → 原子事项 + 覆盖矩阵 + 档位分类	全部
1.5	章节划分	将原子事项分组为 4—10 个章节；随后步骤 2—10 按章节循环执行	dissertation
2	广度扫描	多视角搜索计划 + 并行抓取器波次	全部
3	矛盾图谱	将语料库中的矛盾成对组织为按优先级排序的簇	full
4	关键点分析	两个并行关键点分析 Agent → 带来源预算评分的关键点	full
5	深度调查	K 个并行深度调查 Agent → 具有明确立场的阶段性笔记	full
6	跨关键点协调	协调已明确的立场 → comparisons.md	full
7	来源张力	提取专家分歧 → source-tensions.json	full
8	语料库批评	“什么来源会推翻这一结论？”+ 定向缺口填补抓取	full
9	证据摘要	核心主张 + 原文引述 → evidence-digest.md	full
10	三重草稿	按视角整理来源 + 3 个并行草稿子编排 Agent（light：单份草稿）	全部
11	综合	计划 + 大纲 + 启动综合 Agent → final_report.md	full
12	批评 Agent	4 个并行对抗批评 Agent → 发现结果 JSON	full
13	缺口抓取	针对批评 Agent 指出的 vault 缺口进行定向抓取	full
14	修补	将外科手术式 Edit hunk 应用于草稿（工具锁定为 Read+Edit）	full
14.5	引文检查	验证引文与句子的绑定关系；持怀疑态度的 LLM 抽查；第二轮外科手术式修补	full
15	润色	卫生检查 + 冗余内容处理（工具锁定的 Read+Edit 子 Agent）	全部
16	可读性审计	推荐 Agent 写入 JSON 建议；编排器选择性应用	全部

档位与挡位：两个规模控制杆

档位按查询进行路由。步骤 1 会自动将任务分类为 light 或 full。dissertation 仅可主动启用；请在提示词中提出该要求。

档位	运行内容	典型耗时
light	有界事实查询、综述、比较：1 → 2 → 10 → 15 → 16	约 30—40 分钟
full（默认）	带对抗式审查的深度论证分析：全部 16 步 + 引文检查	在 full 挡位下约 1.5—2.5 小时
dissertation	章节化超大型运行：跨 4—10 个章节处理 300—450 个来源，产出 25K—80K 字	约 4—8 小时

挡位设定标准流水线的规模：即渲染到步骤 skill 中的来源目标、深度预算和字数目标。

hyperresearch profile list           # 所有配置、说明及当前挡位
hyperresearch profile use premier    # 100–130 个来源，双倍深度预算（约 3–5 小时）
hyperresearch profile use full       # 回到 55–80 个来源的基线

挡位会按项目持久保存，重装后仍然存在。自定义挡位：在 .hyperresearch/config.toml 中定义 [profile.<name>]（可配置任意参数：来源目标、关键点上限、草稿数量、字数目标、各 Agent 模型），然后执行 profile use <name>。

运行控制杆：报告采用何种表达方式

档位和挡位决定完成多少工作。控制杆决定输出何种类型的报告，步骤 1 会根据提示词中动词的形式选择它们。提示词中的明确指令始终具有最高优先级。

控制杆	取值	变化内容
register	teach / survey / analyze / advocate	“Teach me X”会得到教学式解释；“what's the landscape”会得到不作结论的领域地图；analyze（默认）会得到评价性论证；advocate 则为某一个指定论点辩护
domain_notes	自由文本	针对所研究领域的来源策略、证据规范和时效窗口
inference_depth	surface / standard / deep	深挖程度控制钮。步骤 4 在看到语料库实际包含的内容后可以提高该级别

这些控制杆会渲染为按角色限定的 shim 文件，启动模板会将其原样粘贴到子 Agent 提示词中，因此批评 Agent 会随表达方式调整，而不是反向抵消它。在 survey 表达方式中，辩证批评 Agent 会标记不公平的呈现，而不是缺少明确立场；润色审计 Agent 也不会再删除保留性措辞。在 advocate 模式中，它们则都会进一步收紧标准。

引文检查器和发布关卡完全不会接收 shim。验证不会因模式而放宽。

hyperresearch levers set <tag> inference_depth=deep --rerender   # 在运行中途进一步深挖
hyperresearch run status -j                                      # 查看步骤 1 做出的选择

两项承重原则

1. **只修补，绝不重新生成。**步骤 11 产出综合报告后（light 档位为步骤 10），后续仅允许进行外科手术式 Edit hunk 修改。修补 Agent 和润色审计 Agent 在 Claude Code 的 allowlist 层面被工具锁定为 [Read, Edit]，因此它们从机制上无法 Write 出一份新草稿。每个 hunk 的上限使“干脆重写它”在技术上不可能实现。无法纳入小 hunk 的批评发现会升级为结构性问题。

2. **规范化研究查询至高无上。**原样保存的用户提示词会一次性持久化至 research/runs/<vault_tag>/query.md，随后每一个步骤及每个启动的子 Agent 都会重新读取它。包装层要求（保存路径、引文格式、末尾章节）则是单独的契约。

模型是 profile 配置，而非硬编码。下表展示内置默认值，你可以在 .hyperresearch/config.toml 中覆盖其中任意一项：在 [profile.full] 中使用 models = { fetcher = "haiku" }，即可在下一次安装或执行 profile use 时，将所有 fetcher 切换为 Haiku。

Agent	默认模型	角色
hyperresearch-fetcher	Sonnet	通过 crawl4ai 抓取 URL；每个波次并行运行 8—12 个
hyperresearch-source-analyst	Sonnet	对任何超过 5000 字的单一长来源进行端到端摘要
hyperresearch-loci-analyst	Sonnet	阅读广度语料库，返回 1—8 个附带理由的深度关键点
hyperresearch-depth-investigator	Sonnet	调查一个关键点，撰写一份具有明确立场的阶段性笔记
hyperresearch-corpus-critic	Sonnet	“什么来源会推翻当前方向？”草稿前缺口分析
hyperresearch-draft-orchestrator	Opus	每个草稿视角各一个；读取其整理后的来源列表并撰写一份草稿
hyperresearch-synthesizer	Opus	阅读全部 3 份草稿，撰写最终报告（两阶段写作，锁定为 Read+Write）
hyperresearch-dialectic-critic	Opus	草稿遗漏的反证据
hyperresearch-depth-critic	Opus	阶段性笔记可以补足的浅层部分
hyperresearch-width-critic	Opus	语料库所支持、但草稿忽略的主题角落
hyperresearch-instruction-critic	Opus	相对提示词原子事项的结构性不匹配
hyperresearch-patcher	Opus	工具锁定为 [Read, Edit]。将批评发现作为外科手术式 Edit hunk 应用
hyperresearch-cite-checker	Sonnet	在发布前以怀疑态度验证抽样的引文—句子绑定关系
hyperresearch-polish-auditor	Opus	工具锁定为 [Read, Edit]。删除冗余内容，清除卫生问题泄漏
hyperresearch-readability-recommender	Opus	为段落节奏以及列表/表格转换写入 JSON 建议
hyperresearch-browser-fetcher	Sonnet	通过驱动你的真实 Chrome（Claude-in-Chrome）清空升级队列

---

Vault：持久、可搜索、可累积

大多数深度研究框架都是一次性的：输出报告，其他内容全部丢弃。Hyperresearch 会保留其读过的内容。每个抓取的来源都会进入由 SQLite 建立索引的 vault，供未来会话在抓取前先行搜索。

hyperresearch search "ion-trap gate fidelity" -j           # 全文搜索
hyperresearch search "quantum" --include-body -j           # 正文全文搜索
hyperresearch note show <id1> <id2> <id3> -j               # 批量读取笔记
hyperresearch graph hubs -j                                # 连接最多的笔记
hyperresearch graph backlinks <id> -j                      # 反向链接
hyperresearch lint -j                                      # 健康检查（断链、缺失标签）

**Markdown 是事实来源，SQLite 是缓存。**笔记以带 YAML frontmatter 的纯 Markdown 文件形式存储在 research/notes/ 中。SQLite 索引可以完全重建：删除它后，hyperresearch sync 会根据 Markdown 重建索引。你可以在任意编辑器中打开 vault，并通过 git 进行版本管理。即使没有安装该工具，你仍能阅读自己的研究资料。

PDF 会被直接抓取。hyperresearch fetch 会自动识别 PDF URL（arXiv、NBER、SSRN、直接的 .pdf 链接），并通过 pymupdf 提取全文。原始 PDF 会保存至 research/raw/<note-id>.pdf，笔记的 raw_file: frontmatter 会链接回该文件。

**来源溯源面包屑。**每个抓取的来源都会携带一个 --suggested-by 链接，指回发现该来源的上游内容。该链路从种子抓取构成一棵有根树；provenance lint 规则会捕捉不连通的组件。

如果需要，还可使用语义搜索。hyperresearch embed sync 会填充嵌入向量（提供商可插拔：voyage、openai，或默认的 none；后者无需任何 API key），而 search --semantic 会将向量相似度与全文排序结合。

策展：笔记具有生命周期

每次会话都会以一次策展流程结束，笔记会随着内容成熟经历 draft → review → evergreen，或随着材料过时经历 stale → deprecated → archive。这正是 vault 不会沦为半读页面垃圾填埋场的原因。

hyperresearch note update <id> --summary "...

The Most Powerful Deep Research Harness

---

Hyperresearch turns Claude Code into a deep research agent: one that currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally). A tier-adaptive 16-step pipeline takes one prompt and produces an adversarially-audited report with full source provenance. Every source it reads lands in a persistent, searchable vault, so each session starts smarter than the last.

Forward-looking projection from a stratified pilot against the DeepResearch-Bench leaderboard snapshot (https://huggingface.co/spaces/muset-ai/DeepResearch-Bench-Leaderboard). Third party validation is pending.

• 250+ sources in a single run. The premier scale profile targets 100–130 in the width sweep alone; citation chasing and gap-fill fetches more than double what actually lands in the corpus.

• Every citation is verified before the report ships. A skeptical cite-checker audits whether each cited source actually supports its sentence. Hallucinated quotes and unacknowledged retractions are hard blocks at the gate.

• Syndication doesn't count as consensus. An independence audit clusters derivative copies, so five reprints of one press release argue with the weight of one source.

• Adversarial by construction. Four critics attack every draft in parallel, and a tool-locked patcher can only apply surgical edits. It physically cannot rewrite the report.

• Paywalled papers get read, not skimmed. A closed paper normally enters a vault as a 1,500-character abstract that the report then cites as though it had been read. Hyperresearch asks Unpaywall and Europe PMC for a legal open-access copy and stores the full text instead, even when the publisher blocks the fetch outright. Every substitution is disclosed in the note, the frontmatter, and the CLI output.

• Nothing is thrown away. Every source lands in a searchable markdown-plus-SQLite vault that your next session reuses before it fetches anything new.

• Crashed runs resume. Each run keeps a manifest; run resume picks up at the exact step where it died.

• Scales from 30 minutes to a dissertation. Bounded queries auto-route to a 5-step fast path. Opt-in dissertation runs write 25K–80K words across chapters, from 300–450 sources.

  cd your-project pip install hyperresearch && hyperresearch install

Then /hyperresearch <anything> in Claude Code.

Python 3.11–3.13. (3.14 not yet supported. Use pyenv install 3.13, uv venv -p 3.13, or py -3.13 -m venv .venv.)

Power users: hyperresearch install --global makes /hyperresearch reachable from every Claude Code session anywhere, at the cost of ~15 lines in every session's system reminder. Per-project install (above) keeps unrelated CC sessions clean.

---

The 16-step research pipeline

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's what stops a long pipeline from quietly dropping steps as its context rots.

| Step | What it does | Tiers

---|---|---|---
1 | Decompose | Canonical query → atomic items + coverage matrix + tier classification | all
1.5 | Chapter partition | Group atomic items into 4–10 chapters; steps 2–10 then loop per chapter | dissertation
2 | Width sweep | Multi-perspective search plan + parallel fetcher waves | all
3 | Contradiction graph | Pair contradictions across the corpus into ranked clusters | full
4 | Loci analysis | Two parallel loci-analysts → scored loci with source budgets | full
5 | Depth investigation | K parallel depth-investigators → interim notes with committed positions | full
6 | Cross-locus reconcile | Reconcile committed positions → comparisons.md | full
7 | Source tensions | Extract expert disagreements → source-tensions.json | full
8 | Corpus critic | "What source would overturn this?" + targeted gap-fill fetch | full
9 | Evidence digest | Top claims + verbatim quotes → evidence-digest.md | full
10 | Triple draft | Per-angle source curation + 3 parallel draft sub-orchestrators (light: single draft) | all
11 | Synthesize | Plan + outline + spawn synthesizer subagent → final_report.md | full
12 | Critics | 4 adversarial critics in parallel → findings JSONs | full
13 | Gap-fetch | Targeted fetch wave for critic-identified vault gaps | full
14 | Patcher | Surgical Edit hunks applied to draft (tool-locked Read+Edit) | full
14.5 | Cite-check | Verify citation-sentence bindings; skeptical LLM spot-check; second surgical patch pass | full
15 | Polish | Hygiene + filler pass (tool-locked Read+Edit subagent) | all
16 | Readability audit | Recommender writes JSON suggestions; orchestrator selectively applies | all

Tiers and gears: the two scale levers

Tiers route per query. Step 1 auto-classifies light vs full. dissertation is opt-in only; ask for it in your prompt.

Tier	What runs	Typical time
light	bounded factual queries, surveys, comparisons: 1 → 2 → 10 → 15 → 16	~30–40 min
full (default)	deep argumentative analysis with adversarial review: all 16 steps + cite-check	~1.5–2.5 h at full gear
dissertation	chaptered mega-runs: 300–450 sources across 4–10 chapters, 25K–80K words	~4–8 hours

Gears set the scale of the standard pipeline: the source targets, depth budgets, and word targets rendered into the step skills.

hyperresearch profile list           # all profiles + descriptions + current gear
hyperresearch profile use premier    # 100–130 sources, doubled depth budget (~3–5 h)
hyperresearch profile use full       # back to the 55–80-source baseline

The gear persists per project and survives reinstalls. Custom gears: define [profile.<name>] in .hyperresearch/config.toml (any knob: source targets, loci caps, draft counts, word targets, per-agent models) and profile use <name>.

Run levers: what voice the report is written in

Tiers and gears set how much work happens. Levers set what kind of report comes out, and step 1 picks them from your prompt's verb shape. An explicit directive in your prompt always wins.

Lever	Values	What changes
register	teach / survey / analyze / advocate	"Teach me X" gets a pedagogical explainer; "what's the landscape" gets a map of the field with no verdict; analyze (the default) gets the evaluative argument; advocate defends one named thesis
domain_notes	freeform	Sourcing strategy, evidence norms, recency window for the field in question
inference_depth	surface / standard / deep	The rabbithole dial. Step 4 can upgrade it after seeing what the corpus actually holds

The levers render into role-scoped shim files that spawn templates paste verbatim 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 missing commitment, and the polish auditor stops striking hedges. In advocate all of them tighten instead.

The cite-checker and the ship gate receive no shim at all. Verification never softens by mode.

hyperresearch levers set <tag> inference_depth=deep --rerender   # go deeper mid-run
hyperresearch run status -j                                      # see what step 1 chose

The two load-bearing principles

1. Patch, never regenerate. After step 11 produces the synthesized report (or step 10 for light tier), the only modifications are surgical Edit hunks. The patcher and 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 "just rewrite it" mechanically impossible. Critic findings that don't fit a small hunk escalate as structural issues.

2. Canonical research query is gospel. The verbatim user prompt is persisted to research/runs/<vault_tag>/query.md once and re-read by every subsequent step and every spawned subagent. Wrapper requirements (save paths, citation format, terminal sections) are a separate contract.

Models are profile config, not hardcode. The table shows the shipped defaults, and you can override any of them in .hyperresearch/config.toml: [profile.full] with models = { fetcher = "haiku" } swaps every fetcher to Haiku on the next install or profile use.

Agent	Default model	Role
hyperresearch-fetcher	Sonnet	URL fetching via crawl4ai; runs 8–12 in parallel per wave
hyperresearch-source-analyst	Sonnet	End-to-end digest of any single long source >5000 words
hyperresearch-loci-analyst	Sonnet	Reads the width corpus, returns 1–8 depth loci with rationale
hyperresearch-depth-investigator	Sonnet	Investigates one locus, writes one interim note with a committed position
hyperresearch-corpus-critic	Sonnet	"What source would overturn the current direction?" pre-draft gap analysis
hyperresearch-draft-orchestrator	Opus	One per draft angle; reads its curated source list and writes one draft
hyperresearch-synthesizer	Opus	Reads all 3 drafts, writes the final report (two-pass write, Read+Write locked)
hyperresearch-dialectic-critic	Opus	Counter-evidence the draft missed
hyperresearch-depth-critic	Opus	Shallow spots interim notes could fill
hyperresearch-width-critic	Opus	Topical corners the corpus supports but the draft ignores
hyperresearch-instruction-critic	Opus	Structural mismatches against the prompt's atomic items
hyperresearch-patcher	Opus	Tool-locked [Read, Edit]. Applies critic findings as surgical Edit hunks
hyperresearch-cite-checker	Sonnet	Skeptically verifies sampled citation-sentence bindings before ship
hyperresearch-polish-auditor	Opus	Tool-locked [Read, Edit]. Cuts filler, strips hygiene leaks
hyperresearch-readability-recommender	Opus	Writes JSON suggestions for paragraph rhythm and list/table conversion
hyperresearch-browser-fetcher	Sonnet	Drains the escalation queue by driving your real Chrome (Claude-in-Chrome)

---

The vault: persistent, searchable, compounding

Most deep research harnesses are one-shot: report out, everything else discarded. Hyperresearch keeps what it reads. Every fetched source lands in a SQLite-indexed vault that future sessions search before they fetch.

hyperresearch search "ion-trap gate fidelity" -j           # Full-text search
hyperresearch search "quantum" --include-body -j           # Full-body search
hyperresearch note show <id1> <id2> <id3> -j               # Batch-read notes
hyperresearch graph hubs -j                                # Most-connected notes
hyperresearch graph backlinks <id> -j                      # Reverse links
hyperresearch lint -j                                      # Health check (broken links, missing tags)

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 the markdown. Open the vault in any editor, version it in git. You don't need the tool installed to read your own research.

PDFs fetch directly. hyperresearch fetch auto-detects PDF URLs (arXiv, NBER, SSRN, direct .pdf links) and extracts full text via pymupdf. Raw PDFs land in research/raw/<note-id>.pdf and the note's raw_file: frontmatter links back.

Provenance breadcrumbs. Every fetched source carries a --suggested-by link back to whatever surfaced it. The chain forms a rooted tree from seed fetches; the provenance lint rule catches disconnected components.

Semantic search, if you want it. hyperresearch embed sync populates embeddings (provider-pluggable: voyage, openai, or the default none, which needs zero API keys) and search --semantic blends vector similarity with full-text ranking.

Curation: notes have a lifecycle

Every session ends with a curation pass, and notes move through draft → review → evergreen, or stale → deprecated → archive as material ages out. That's what keeps a vault from turning into a landfill of half-read pages.

hyperresearch note update <id> --summary "..." --add-tag <t> -j   # promote a draft
hyperresearch dedup -j                                            # near-duplicate pairs by content similarity
hyperresearch topic tree -j                                       # the topic hierarchy
hyperresearch index build -j                                      # regenerate index pages
hyperresearch batch set-status stale --tag <t> -j                 # bulk lifecycle moves
hyperresearch link --note <id> --dry-run -j                       # wiki-links the linker would add

The vault is markdown in a directory. Everything below is a convenience on top of that, not a dependency.

hyperresearch export json -o out.json # every note as structured JSON
hyperresearch export vault <dir>      # a filtered subset to another directory
hyperresearch import <dir>            # pull an existing markdown collection in
hyperresearch git changed -j          # notes with uncommitted changes
hyperresearch git log -j              # notes touched by recent commits
hyperresearch watch                   # auto-sync while you edit in your own editor

---

Use the vault outside Claude Code

An MCP server. pip install hyperresearch[mcp], then hyperresearch mcp speaks stdio, so Claude Desktop, Cursor, or anything else that speaks MCP can work the same vault. Thirteen tools: search_notes, read_note, read_many, list_notes, get_backlinks, get_hubs, vault_status, lint_vault, check_source, list_sources, fetch_url, create_note, update_note.

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 and no JavaScript dependencies.

---

Source ranking: quality is persistent, not vibes

Every source accumulates a composite quality_score built from source-type tier, fetch-time utility, citation authority (from OpenAlex / Semantic Scholar, including retraction flags), and vault PageRank centrality:

hyperresearch sources score -j             # Enrich DOI-bearing notes: citations, venue, retractions
hyperresearch graph rank -j                # PageRank over the link + provenance graph
hyperresearch search "q" --ranked -j       # Quality-weighted full-text search
hyperresearch sources independence -j      # Cluster syndicated/derivative copies: 5 copies of one press release = 1 vote
hyperresearch claims search "q" -j         # Query extracted claims across all sources

Retracted sources are floored to near-zero quality, and a ship-time retraction sweep re-checks every cited DOI fresh, so a retraction published yesterday is caught today. Even on vault sources reused from old runs.

---

Runs: resumable, budgeted, verified

Every run owns an isolated workspace (research/runs/<vault_tag>/) and a manifest. Concurrent runs never collide, and a crashed run resumes exactly where it stopped:

hyperresearch run status -j          # Step-by-step status, spend, escalation queue depth
hyperresearch run resume -j          # Exact next step + Skill invocation to continue
hyperresearch run report -j          # Per-step wall-time / spend / source-yield telemetry
hyperresearch run verify <tag> -j    # Ship gate: headings, length, citation density, cite-check resolution

run init --budget 50 caps estimated API-equivalent spend; crossing the cap blocks the run rather than letting it quietly balloon. And before any report ships, the verification battery runs: quote-integrity (every quoted span must exist verbatim in a vault note), retracted-citations (citing a retracted source unacknowledged blocks the ship), numeric-consistency (numbers untraceable to evidence get flagged), plus the cite-check step's per-citation binding audit.

---

What's structurally enforced

• Verbatim prompt as gospel. scaffold-prompt lint blocks if the scaffold doesn't open with the user's exact prompt
• Locus coverage. Every step 4 locus must have a step 5 interim note; missing interims flag as errors
• Patch-only modification. Steps 14, 15, 16 are tool-locked to [Read, Edit]. They cannot regenerate the draft
• Critical findings never silently skip. patch-surgery lint surfaces any critical finding the patcher couldn't apply
• Quoted text must exist. quote-integrity lint blocks any quoted span that doesn't appear verbatim in a vault note; hallucinated quotes cannot ship
• Retractions block the ship. Citing a retracted source without acknowledging the retraction is a hard error at the final gate
• Schema integrity. tier, content_type, and type are SQLite CHECK-constrained vocabularies; corrupted frontmatter cannot poison the index
• Hygiene leaks caught on the way out. Scaffold sections, YAML frontmatter, and prompt echoes are stripped by step 15 before ship
• Fetched text is data, never instructions. Web-fetched bodies are served inside an <untrusted-source> fence on both note show and search, so a page telling the agent to ignore its instructions is read as content

---

A research agent reads hundreds of pages it did not choose, and any one of them can contain text addressed to the agent rather than to you.

Every body fetched from the web is served wrapped in <untrusted-source url="..."> delimiters with an inline treat-as-data preamble, on both paths that serve bodies (note show in single, batch, and JSON forms, and search with bodies included). Notes your own pipeline subagents wrote pass through unwrapped. Forged fence tags inside a fetched body are neutralized and left visible for forensics, the url attribute is HTML-escaped with control characters stripped, and in search the wrapping happens after token-budget truncation so the closing fence can never be severed. The fetcher, depth-investigator, draft-orchestrator, and source-analyst prompts all carry a policy block telling them not to launder a fenced page's directives into trusted output.

Resolved URLs from third-party APIs get the same treatment. An open-access location arrives inside someone else's JSON, so it's checked for scheme, embedded credentials, and publicly-routable resolution before anything fetches it.

---

Authenticated crawling + the browser lane

Fetch from LinkedIn, Twitter, paywalled sites or anything you can log into:

hyperresearch setup       # Browser opens. Log into your sites. Done.

LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible browser to avoid session kills.

Blocked fetches escalate instead of dying. When headless crawling hits a login wall or bot wall mid-run, the URL queues as an escalation (hyperresearch escalation list -j). If you have the Claude-in-Chrome extension, the browser-fetcher agent drains the queue by driving your real, logged-in Chrome. Hard boundary: CAPTCHAs, 2FA, and logins are never solved automatically. They're consolidated into one message and handed to you.

---

Academic APIs before web search

For any topic with a research literature, hit academic APIs BEFORE web search. They return citation-ranked canonical papers; web search returns derivative commentary.

• Semantic Scholar: https://api.semanticscholar.org/graph/v1/paper/search
• arXiv: https://export.arxiv.org/api/query
• OpenAlex: https://api.openalex.org/works
• PubMed: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi

After the academic sweep, run web searches for context, news, non-academic angles, and at least one adversarial search ("criticism of X", "limitations of X").

---

Open-access full text: read this before you cite

A paywalled paper otherwise enters the vault as an abstract, and the pipeline then reasons over ~1,500 characters while citing the work as though the paper had been read. To close that, when a fetch lands a thin page carrying a DOI, hyperresearch asks Unpaywall and Europe PMC for a legal open-access copy and stores that text in the note body instead.

The note'ssource: still points at the URL you asked for. The body may have come from somewhere else. That substitution is disclosed in four places, and you should know all of them:

1. A banner at the top of the note body, naming the URL the text actually came from and which version it is.
2. oa_url / oa_source / oa_version / oa_license / oa_recovery_kind in the note's frontmatter.
3. An oa block in hpr note show <id> --json, carrying body_is_not_from_source: true.
4. A line in the output of hpr fetch and hpr fetch-batch.

Rescued notes: nothing in them came from the source

The same lookup runs when a source can't be read at all — a 403, a login wall, a bot wall. Those are where a paywalled paper is most completely lost, and, since a DOI identifies the work rather than the host, where a legal copy is most likely to exist elsewhere.

A note built that way is a stronger claim than a substitution, and it is marked differently: oa_recovery_kind: rescued, nothing_from_source: true in note show, and a banner that says the source URL was never read. Take it literally. The title, the authors, and every word of the body are the open-access copy's — nothing was read from the URL in source:. If you would rather have no note than a note assembled entirely from a substitute, set oa_rescue_blocked = false.

Two limits worth knowing. Rescue needs a DOI, and a source that returned nothing offers no page to read one out of, so it only fires when the DOI is in the URL itself (a doi.org link) or in a wall page's citation_doi meta tag. A bare publisher URL with no DOI in it fails exactly as it did before. And a rescued source is not queued for the browser-escalation lane, because the paper is already in hand — if you want the publisher's own page specifically, fetch it through that lane yourself.

Versions are not interchangeable. Unpaywall will happily hand back an accepted manuscript or a submitted preprint when no published copy is open. hyperresearch prefers the version of record and records what it got in oa_version, but if that says acceptedVersion or submittedVersion, check any direct quotation against the published paper before it reaches a report. The body banner says so too.

Configure it under [scholar] in .hyperresearch/config.toml:

[scholar]
oa_recovery = true              # set false to disable entirely
contact_email = ""              # REQUIRED by Unpaywall's terms — empty means Unpaywall is skipped
oa_min_full_text_chars = 6000   # bodies shorter than this trigger a lookup
oa_prefer_published = true      # version of record over preprints
oa_max_attempts = 3             # candidate copies to try before giving up
oa_rescue_blocked = true        # also run when the source can't be read at all

Out of the box contact_email is empty, so only Europe PMC runs and recovery is limited to papers in its open-access subset. Set it to a real address to enable Unpaywall — their terms require one, and shipping a shared placeholder would get that placeholder rate-limited for every hyperresearch user at once.

Publishers block their own open-access PDFs often enough that one attempt isn't enough, so hyperresearch walks a candidate list: every PDF Unpaywall knows about, then the landing pages, then Europe PMC's structured full text (parsed from JATS, which beats pymupdf on a two-column PDF — real section boundaries, no header bleed, no column interleaving). Europe PMC is only queried once Unpaywall's copies are exhausted.

Recovery never fails a fetch and never lowers quality. A candidate has to clear two bars to be accepted: more text than you already had, and enough text to clear oa_min_full_text_chars. That second bar is what stops a repository record page — title, authors, a 200-word summary — from passing for full text just by being marginally longer than the publisher's abstract. If no candidate clears both, you keep the abstract and no oa block appears. Rescue only ever turns a failed fetch into a note, never the reverse: when a blocked source has no open-access copy, the command fails exactly as it always did.

---

• It doesn't replace your judgment on which sources matter. The agent picks, you steer.
• It can't fetch what's behind a paywall you haven't logged into. Open-access recovery finds a legal free copy when one exists — even when the publisher blocks the fetch outright — but when none exists you get the abstract, or nothing, and the note says so.
• It runs on Anthropic models via the subagent roster (per-agent assignments come from the profile's model map). Usage scales with tier, gear, and corpus size. If anyone wants to port this to Codex, put up a PR!
• The lint gate catches structural failures (missing scaffold, broken provenance, unresolved CRITICALs). It cannot guarantee factual accuracy, that's still your call.

---

---

MIT

---