Overview

Hyperresearch is a Python package plus agent skill that turns Claude Code or OpenAI Codex into a deep-research harness. A single prompt drives a tiered pipeline that decomposes the question, fetches sources from the web and scholarly databases, drafts and critiques a report, then checks citations before shipping. Every fetched source is stored in a persistent, searchable vault so later sessions can reuse it. It targets researchers and analysts who already work in one of those coding agents and want cited, auditable reports rather than one-shot summaries.

The pipeline has 16 steps. light runs a five-step fast path for bounded questions, full runs all steps with four adversarial critics and a cite-check pass, and dissertation is an experimental chaptered mode for very long reports (tiers and steps). Two scale levers control the work: tiers route per query, while gears set source and depth targets (profile commands).

Getting started

Requirements are Python 3.11+ and the Claude Code or OpenAI Codex CLI. A minimal Claude Code setup:

cd your-project
pip install hyperresearch
hyperresearch install

Then invoke /hyperresearch <question> in Claude Code. The project can also be installed as a plugin or a single skill, but the Python package is still required (install options).

For Codex, install the Codex target and start the session with write and network access, which Codex disallows by default:

pip install hyperresearch && hyperresearch install . --target codex
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true

Then run $hyperresearch <question> in the session (Codex setup). The README notes that Codex support lands in the next PyPI release; until then, install from the GitHub URL it gives.

Run output, notes and reports live under research/. You can inspect and resume runs with hyperresearch run status -j and hyperresearch run resume -j, and search the vault with hyperresearch search "<terms>" -j (vault commands).

Usage constraints

• The pipeline runs on Anthropic models in Claude Code and on the session's model in Codex; usage and spend scale with tier, gear and corpus size. run init --budget <n> caps estimated API-equivalent spend.
• Codex lacks the Claude-in-Chrome browser lane, so login-walled fetches remain queued instead of being retrieved automatically; its per-agent tool locks are instructions rather than enforcement (Codex differences).
• Paywalled sources are recovered only when a legal open-access copy exists. When a full substitute is used, the note is marked rescued and says nothing came from the original URL. Unpaywall recovery requires a contact email; without one, only Europe PMC's open-access subset is queried.
• The dissertation tier is experimental; its length, read-budget and citation targets are not yet fully wired (issue #103).
• The final gate checks structure and citation integrity, not factual correctness; choosing which sources matter remains the user's job.
• Python 3.11–3.14 is supported, and the project is MIT licensed.

HotRepo's take

The repository is recent (created April 2026) and HotRepo recorded 118 stars on 11 September 2026 and 153 the next day, then 27 more on 3 November, when it reached 16th on the Python daily board at 4,355 stars. Those snapshots are not the same-day all-language rank, so they do not establish a continuous trend. What stands out technically is the design around auditability: citation-sentence verification, a ship gate that blocks unacknowledged retractions and verbatim quote mismatches, and markdown-first storage that keeps the vault readable without the tool (enforcement rules). The README's first-place DRACO claim is the author's own benchmark result, not independently reproduced here, and the Codex port has not been benchmarked.