hyperresearch

Hyperresearch turns Claude Code into a deep research agent. A single prompt is decomposed into atomic research items, routed through a tier-adaptive pipeline (light, full, or dissertation), and built up through parallel web-search waves, contradiction-graph analysis, depth investigation of the most contested claims, and a triple-draft synthesis stage before the report ever reaches a human reader.

What sets it apart from a typical research-agent script is the adversarial gate at the end: four critics attack the draft in parallel, a tool-locked patcher can only apply surgical Edit hunks (never a full rewrite), and a skeptical cite-checker verifies that every cited sentence is actually supported by its source before the report ships. An independence audit also clusters derivative copies of the same underlying story so that five reprints of one press release do not count as five corroborating sources.

Every source the pipeline reads is written into a persistent, searchable markdown-plus-SQLite vault rather than discarded once the report is generated, so a later research session on a related topic starts from an already-populated corpus instead of fetching everything from scratch. A dedicated scholar-search command fans a single query out across OpenAlex, Crossref, CORE, DOAB, ClinicalTrials.gov, SEC EDGAR, and FRED, deduplicating by DOI and title.

The project ships as a pip-installable Python package that scaffolds itself into a Claude Code project as a set of Skills, so the actual orchestration logic runs as Claude Code subagents rather than as an external service calling an LLM API directly.

What You Get

• A /hyperresearch <query> Claude Code skill that auto-classifies a query into a light (fast, bounded), full (default, adversarially reviewed), or dissertation (chaptered, 25K-80K word) research run
• A persistent markdown-plus-SQLite vault of every source ever fetched, reused across sessions instead of being thrown away after each report
• Four parallel adversarial critics (dialectic, depth, width, instruction) plus a tool-locked patcher restricted to surgical Edit hunks, so a report can be revised but never silently regenerated
• A skeptical cite-checker that verifies sampled citation-to-sentence bindings before a report is allowed to ship
• A unified scholar-search CLI (hpr scholar search) that queries OpenAlex, Crossref, CORE, DOAB, ClinicalTrials.gov, SEC EDGAR, and FRED through one client and deduplicates results by DOI/title
• Open-access recovery that swaps a paywalled paper’s 1,500-character abstract for a full-text copy from Unpaywall, Europe PMC, or CORE when one is legally available
• Crash-resumable runs: every run keeps a manifest, and hpr run resume picks back up at the exact step it died on
• Configurable ‘gears’ (source-count and depth-budget profiles like premier vs full) and ‘levers’ (register/domain/inference-depth) that change how much work runs and what voice the final report is written in

Common Use Cases

• Producing a fully-cited literature review or market analysis from a single prompt, with every claim traceable to a stored source
• Running a bounded, fast fact-finding query (the light tier) when a full adversarial pipeline would be overkill
• Building a compounding internal knowledge base for a team or individual researcher, where each new research run reuses sources fetched by earlier ones
• Academic or policy research that needs scholarly-database coverage (OpenAlex, Crossref, SEC filings, clinical trials) rather than just general web search
• Long-form dissertation-scale writing (25K-80K words across chapters) assembled from 300-450 sources in a single orchestrated run

Under The Hood

Architecture Hyperresearch is structured as a thin CLI/skill router (src/hyperresearch/cli/main.py, run_cmd.py, research.py) sitting on top of a core/ package that owns the vault (core/vault.py), a versioned SQLite schema with WAL mode and foreign keys (core/db.py, currently schema version 12 with migration support), and per-domain logic modules (fetcher, citecheck, claims, embed, escalation, graphrank, independence, oa, scholar, sync). The actual 16-step research pipeline is not implemented as Python control flow at all — it is a set of markdown Skill files (src/hyperresearch/skills/hyperresearch-N-*.md) that Claude Code’s own Skill tool loads one phase at a time, so a long-running pipeline can’t quietly drop a step as its context window fills up; each step’s subagents (fetcher, loci-analyst, depth-investigator, critics, patcher, cite-checker) are declared with specific model tiers and, in the patcher and polish-auditor’s case, are deliberately tool-locked to Read+Edit so they cannot rewrite a draft outright. A run’s canonical query is persisted once to research/runs/<tag>/query.md and re-read by every subsequent step, and every run tag is validated against a strict slug regex before being joined onto a filesystem path, closing off a directory-traversal class of bug the project’s own issue tracker had previously hit.

Tech Stack The project is a Python 3.11-3.13 package built with hatchling and distributed via PyPI, using Typer for the CLI surface, Rich for terminal output, Pydantic for data models, Jinja2 for templating, and httpx for HTTP. Storage is local SQLite (accessed through the standard library, not an ORM) rather than a hosted database, keeping the vault fully self-contained per project. Web fetching goes through Crawl4AI as an optional extra, an MCP server integration is gated behind a pinned mcp version range to avoid a documented breaking change in mcp 2.x, and academic-source coverage is implemented as a set of dedicated provider modules under scholar/providers/ (OpenAlex, Crossref, CORE, DOAB, ClinicalTrials.gov, SEC EDGAR, FRED) behind one client layer. Optional extras (exa, tavily, watchdog) are cleanly separated in pyproject.toml so installing one integration doesn’t force unrelated SDK upgrades.

Code Quality The repository has 63 test files under tests/, organized to mirror the source tree (test_core/, test_cli/, test_graph/, test_mcp/, test_scholar/, test_search/, test_serve/, test_web/), run through pytest with fixtures (a seeded_vault fixture is used across multiple suites) and offline-only setups where practical. CI runs on GitHub Actions across Python 3.11-3.13 on Ubuntu plus a dedicated Windows job specifically because the maintainer develops on Windows and past bugs traced to socket/path/signal differences between platforms, and every push also runs ruff check before pytest and a package build step. Source comments consistently explain the ‘why’ behind a defensive check (an orphaned-row reclaim function, a run-tag validation regex) by referencing the specific bug or issue number that motivated it, which is a stronger-than-typical signal of a maintained, incident-driven codebase rather than only forward-looking feature work.

What Makes It Unique Most single-shot research-agent tools synthesize a report and discard everything they read; hyperresearch’s core bet is that the fetched corpus is the actual asset, so it persists every source into a reusable, searchable vault that compounds across sessions. Its adversarial-review stage goes further than typical LLM self-critique by physically constraining what the review stage can do: the patcher and polish-auditor subagents are tool-locked to Read+Edit only, so a critic’s finding can only ever become a bounded surgical hunk rather than a full-draft rewrite, and a separate independence audit clusters syndicated copies of the same underlying story so republished press releases don’t inflate apparent source diversity. Running the entire orchestration as Claude Code Skills and subagents, rather than as a standalone service with its own LLM-calling loop, is also an atypical architectural choice for this category of tool.

Self-Hosting

Licensing Model MIT licensed — all features, including the full 16-step pipeline, the MCP server, and every scholar-source integration, are available with no license key or paid tier of any kind.