hyperresearch

<img width="1280" height="400" alt="hyperresearch-readme-hero-1280x400" src="https://github.com/user-attachments/assets/320680fc-bc56-4eac-9ec2-7ec46d4bde98" /> <h3 align="center">The Most Powerful Deep Research Harness: a deep research skill for Claude Code and OpenAI Codex</h3> <p align="center"> <a href="https://pypi.org/project/hyperresearch/"><img src="https://img.shields.io/pypi/v/hyperresearch" alt="PyPI version"></a> <a href="https://pypi.org/project/hyperresearch/"><img src="https://img.shields.io/pypi/pyversions/hyperresearch" alt="Python 3.11+"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/jordan-gibbs/hyperresearch" alt="License: MIT"></a> <a href="https://github.com/jordan-gibbs/hyperresearch"><img src="https://img.shields.io/github/stars/jordan-gibbs/hyperresearch?style=social" alt="GitHub stars"></a> </p> <p align="center"> <a href="#install"><img src="https://img.shields.io/badge/Claude%20Code-supported-D97757" alt="Works in Claude Code"></a> <a href="#codex"><img src="https://img.shields.io/badge/OpenAI%20Codex-supported-10A37F" alt="Works in OpenAI Codex"></a> <a href="https://hyperresearch.ai/?utm_source=github&utm_medium=readme"><img src="https://img.shields.io/badge/Hosted-hyperresearch.ai-4F46E5" alt="Hosted at hyperresearch.ai"></a> </p>

---

Hyperresearch turns Claude Code into a deep research agent: one that currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally). It runs in OpenAI Codex too. 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.

Don't want to run it locally? Hyperresearch is the hosted version: the same pipeline, with no Claude Code or Codex install needed.

[!NOTE] New: hyperresearch runs on OpenAI Codex. One command installs the full pipeline for Codex: entry skill, step procedures, the subagent roster as Codex custom agents, and a Stop hook that keeps Codex from skipping steps. Same vault, same ship gate as on Claude Code.

pip install hyperresearch && hyperresearch install . --target codex
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true   # then: $hyperresearch <question>

Codex support ships in the next PyPI release; until then install from GitHub with pip install git+https://github.com/jordan-gibbs/hyperresearch. Details and what differs on Codex: Codex.

<p align="center"> <img src="assets/benchmark.png" alt="DeepResearch-Bench top-5 hyperresearch leads the chart ahead of Grep Deep Research, Cellcog Max, nvidia-aiq, Gemini Deep Research, and OpenAI Deep Research" width="780"> </p> <p align="center">_{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.}</p>

Why it wins

• 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.
• Eight scholarly sources, one query. hpr scholar search hits OpenAlex, Crossref, CORE, DOAB, ClinicalTrials.gov, SEC EDGAR and FRED through one client layer and returns a single list deduplicated by DOI and title. Books, trials and filings come back alongside papers, each tagged so the pipeline knows which is which. The humanities and social sciences are covered on purpose, not as an afterthought.
• 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, Europe PMC and CORE 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 (experimental) write 25K–80K words across chapters, from 300–450 sources.

Browse the vault by DOI, venue, citation count, retraction status, or retrieved manuscript version with scholarly metadata filters.

Install

Works in Claude Code and OpenAI Codex: same pipeline, same vault.

cd your-project
pip install hyperresearch

hyperresearch install                    # Claude Code, then: /hyperresearch <anything>
hyperresearch install . --target codex   # OpenAI Codex, then: $hyperresearch <anything>

--target all installs both side by side. Codex sessions need write access and network, see below.

Prefer a plugin or a single skill? Each route below installs one bootstrap skill, deep-research, that sets the pipeline up in the current project on first use. It still needs pip install hyperresearch.

| | Claude Code | OpenAI Codex | |---|---|---| | Plugin | /plugin marketplace add jordan-gibbs/hyperresearch<br>/plugin install hyperresearch@hyperresearch | codex plugin marketplace add jordan-gibbs/hyperresearch<br>codex plugin add hyperresearch@hyperresearch | | Skill (skills.sh) | npx skills add jordan-gibbs/hyperresearch -a claude-code | npx skills add jordan-gibbs/hyperresearch -a codex | | Invoke | /hyperresearch:deep-research <question> (plugin)<br>/deep-research <question> (skill) | $hyperresearch:deep-research <question> (plugin)<br>$deep-research <question> (skill) |

Or just ask for deep research in plain words; the skill triggers on its description.

Python 3.11–3.14.

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 bootstrap skill

The repo is a Claude Code plugin marketplace, a Codex plugin marketplace, and a skills.sh source, and all three ship the same skill, deep-research. It checks for the hyperresearch CLI, runs hyperresearch install for the agent it is running in (--target codex under Codex), and hands off to the pipeline. The pipeline itself still comes from the Python package.

If Claude Code does not pick up the newly installed skills and subagents, restart it in the same directory and run /hyperresearch <question>. Codex discovers skills at session start, so on first use the bootstrap reads the freshly installed entry skill directly; later sessions can start with $hyperresearch <question>.

Codex

The same pipeline runs on the OpenAI Codex CLI.

cd your-project
pip install hyperresearch && hyperresearch install . --target codex

This installs the entry skill at .agents/skills/hyperresearch/, the step procedures under .hyperresearch/codex/steps/, the subagents as custom agents in .codex/agents/, a Stop hook in .codex/hooks.json, and a short block in AGENTS.md. --target all installs the Claude Code and Codex versions side by side. --global --target codex puts the entry skill in ~/.agents/skills/ and the agents in ~/.codex/agents/.

Research needs to write files and reach the network, and Codex allows neither by default. Start the session with both enabled, then invoke the skill:

codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true
# then, in the session:
$hyperresearch <anything>

# non-interactive:
codex exec --sandbox workspace-write -c sandbox_workspace_write.network_access=true \
  --dangerously-bypass-hook-trust "\$hyperresearch <anything>"

You pass these as flags; hyperresearch never edits your Codex config. codex exec cannot ask you to trust the project's hooks, so without --dangerously-bypass-hook-trust the Stop hook below does not run. Only pass it for hooks you have read (.codex/hooks.json).

Subagents inherit the session's model. To pin a model per role, add a codex_models override to a profile in .hyperresearch/config.toml and re-run hyperresearch install . --target codex:

[profile.full]
codex_models = { fetcher = "gpt-5.4-mini", critics = "gpt-5.5" }

What is different on Codex:

• No browser lane. Codex has no Claude-in-Chrome equivalent, so fetches blocked by a login wall or bot wall stay in the escalation queue, and the final message lists them for you.
• Tool locks are instructions, not enforcement. Codex custom agents have no per-agent tool allowlist. The patcher and polish auditor are told to make surgical edits only, but nothing stops them from doing more.
• A Stop hook guards the pipeline. hyperresearch run stop-gate blocks the session from ending while the newest run is mid-pipeline, so Codex cannot quietly answer inline and stop. Codex runs a project's hooks only after you trust them.

---

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 (on Codex, it reads one step file per phase from .hyperresearch/codex/steps/). 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