Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
chart + banner refresh for launch (#11)
Jordan Gibbs951ccc09f085
diff --git a/README.md b/README.mdindex 0603edb..3316296 100644--- a/README.md+++ b/README.md@@ -2,7 +2,7 @@<img src="assets/banner.png" alt="HYPERRESEARCH" width="700"></p>-<h3 align="center">A Deep Research Harness for Claude Code</h3>+<h3 align="center">The Most Powerful Deep Research Harness</h3><p align="center"><a href="https://pypi.org/project/hyperresearch/"><img src="https://img.shields.io/pypi/v/hyperresearch" alt="PyPI version"></a>@@ -13,13 +13,13 @@----**Hyperresearch turns Claude Code into a deep research agent — and currently leads the DeepResearch-Bench RACE leaderboard internally.** A tier-adaptive 16-step pipeline produces adversarially-audited reports with full source provenance. Every fetched source lands in a persistent, searchable vault that compounds across sessions.+**Hyperresearch turns Claude Code into a deep research agent. and currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally).** A tier-adaptive 16-step pipeline produces adversarially-audited reports with full source provenance. Every fetched source lands in a persistent, searchable vault that compounds across sessions.<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"><sub>Forward-looking projection from a stratified pilot against the DeepResearch-Bench leaderboard snapshot (muset-ai/DeepResearch-Bench-Leaderboard). Full 100-query sweep pending.</sub></p>+<p align="center"><sub>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.</sub></p>## Install@@ -28,20 +28,13 @@ pip install hyperresearchhyperresearch install```-In Claude Code, type `/hyperresearch <anything>`. Step 1 classifies your query into one of two tiers and the rest of the pipeline scales accordingly:--| Tier | Steps that run | Typical time |-|---|---|---|-| `light` | bounded factual queries, surveys, comparisons — 1 → 2 → 10 → 15 → 16 | ~30–40 min |-| `full` | deep argumentative analysis with adversarial review — all 16 steps | ~1.5–2.5 hours |--The single install command provisions a SQLite vault, auto-installs Chromium for headless browsing, generates `CLAUDE.md`, registers the `/hyperresearch` entry skill, installs all 16 step skills, and wires the agent roster + PreToolUse hooks into `.claude/`.+Then, in a fresh Claude Code session, type `/hyperresearch <anything>`.----## How it works — the 16-step pipeline+## The 16-step research pipeline-The entry skill is a thin **router**. It bootstraps the canonical research query, then invokes one step skill per pipeline phase via Claude Code's `Skill` tool. Each step's procedure is loaded fresh into context only when needed — defeating the context-compaction problem that makes monolithic long pipelines silently drop steps.+The entry skill is a thin router. It bootstraps the canonical research query, then invokes one step skill per pipeline phase via Claude Code's `Skill` tool. Each step's procedure is loaded fresh into context only when needed defeating context-rot problems that makes long pipelines silently drop steps.| # | Step | What it does | Tiers ||---|---|---|---|@@ -62,11 +55,20 @@ The entry skill is a thin **router**. It bootstraps the canonical research query| 15 | Polish | Hygiene + filler pass (tool-locked Read+Edit subagent) | both || 16 | Readability audit | Recommender writes JSON suggestions; orchestrator selectively applies | both |-### The two load-bearing invariants+### Depth Modes++In your prompt, you can request one of two tiers and the rest of the pipeline scales accordingly. Full mode is default.++| Tier | Steps that run | Typical time |+|---|---|---|+| `light` | bounded factual queries, surveys, comparisons — 1 → 2 → 10 → 15 → 16 | ~30–40 min |+| `full` | deep argumentative analysis with adversarial review — all 16 steps | ~1.5–2.5 hours |++### 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 — 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.+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/query-<vault_tag>.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 — they never contaminate the query itself.+2. **Canonical research query is gospel.** The verbatim user prompt is persisted to `research/query-<vault_tag>.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.### Subagent roster@@ -91,7 +93,7 @@ The entry skill is a thin **router**. It bootstraps the canonical research query## The vault: persistent, searchable, compounding-Hyperresearch is not a one-shot report generator. Every fetched source lands in a SQLite-indexed vault that every future research session can reuse.+Hyperresearch is not a one-shot report generator like most other Deep research harnesses. Every fetched source lands in a SQLite-indexed vault that every future research session can reuse.```bashhyperresearch search "ion-trap gate fidelity" -j # Full-text search@@ -102,7 +104,7 @@ hyperresearch graph backlinks <id> -j # Reverse linkshyperresearch 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. The vault is inspectable in any editor, version-controllable in git, and readable without the tool installed.+**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. The vault is inspectable in any editor, version-controllable in git, and readable without the tool installed.**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.@@ -123,7 +125,7 @@ hyperresearch lint -j # Health check (broke## Authenticated crawling-Fetch from LinkedIn, Twitter, paywalled sites — anything you can log into:+Fetch from LinkedIn, Twitter, paywalled sites or anything you can log into:```bashhyperresearch setup # Browser opens. Log into your sites. Done.@@ -148,19 +150,17 @@ After the academic sweep, run web searches for context, news, non-academic angle## What it doesn't do-- It doesn't replace your judgment on which sources matter — the agent picks, you steer.+- 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.-- It runs on Anthropic models — Opus + Sonnet + Haiku via the subagent roster. Costs scale with tier and corpus size.-- The lint gate catches **structural** failures (missing scaffold, broken provenance, unresolved CRITICALs). It cannot guarantee factual accuracy — that's still your call.+- It runs on Anthropic models Opus + Sonnet + Haiku via the subagent roster. Costs scale with tier 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.---## Requirements- Python 3.11+-- [Claude Code](https://claude.com/claude-code) with Anthropic API access-- API key with access to Opus, Sonnet, and Haiku — one key powers the full roster-- Windows, macOS, Linux+- [Claude Code](https://claude.com/claude-code)---diff --git a/assets/_generate_banner.py b/assets/_generate_banner.pynew file mode 100644index 0000000..64368c4--- /dev/null+++ b/assets/_generate_banner.py@@ -0,0 +1,56 @@+"""Regenerate banner.png at GitHub-social-preview dimensions (1280x640).++Takes the existing pixel-art wordmark (584x250), upscales it 2x with+nearest-neighbor to preserve the chunky pixel aesthetic, and places it+centered on a 1280x640 dark canvas matching the benchmark chart's+background color so the README header + social preview + Star History+icon all read as one visual system.++Output: assets/banner.png (overwrites)+"""++from pathlib import Path++from PIL import Image++ASSETS = Path(__file__).parent+SRC = ASSETS / "banner.png"+OUT = ASSETS / "banner.png"++# Match the chart's dark background so the README header + chart + social+# preview share one visual treatment.+BG = (14, 17, 22, 255) # #0E1116+TARGET_W, TARGET_H = 1280, 640++src = Image.open(SRC).convert("RGBA")++# Upscale the wordmark 2x with nearest-neighbor — preserves the pixel-art+# chunky letterforms instead of blurring them.+upscaled = src.resize((src.width * 2, src.height * 2), Image.NEAREST)++# Cap at ~70% of canvas height so the wordmark doesn't crowd the edges+max_h = int(TARGET_H * 0.70)+if upscaled.height > max_h:+ ratio = max_h / upscaled.height+ upscaled = upscaled.resize(+ (int(upscaled.width * ratio), max_h),+ Image.NEAREST,+ )++# Cap at ~85% of canvas width+max_w = int(TARGET_W * 0.85)+if upscaled.width > max_w:+ ratio = max_w / upscaled.width+ upscaled = upscaled.resize(+ (max_w, int(upscaled.height * ratio)),+ Image.NEAREST,+ )++# Compose onto target canvas, centered+canvas = Image.new("RGBA", (TARGET_W, TARGET_H), BG)+x = (TARGET_W - upscaled.width) // 2+y = (TARGET_H - upscaled.height) // 2+canvas.paste(upscaled, (x, y), upscaled)++canvas.convert("RGB").save(OUT, "PNG", optimize=True)+print(f"wrote {OUT} ({TARGET_W}x{TARGET_H})")diff --git a/assets/_generate_benchmark.py b/assets/_generate_benchmark.pyindex 732bdb9..b41f102 100644--- a/assets/_generate_benchmark.py+++ b/assets/_generate_benchmark.py@@ -1,9 +1,11 @@"""Generate the DeepResearch-Bench leaderboard chart for the README.Numbers sourced from deepresearch-bench.github.io and the DRB GitHub-repository as of 2026-04-15. hyperresearch at 57.5 is a forward-looking-projection based on the Q91 pilot lift (+2.08 over a 52.74 v1 baseline);-full 100-query sweep pending. Regenerate when leaderboard updates.+repository as of 2026-04-29. hyperresearch at 57.77 is the V8.3+stratified pilot mean across 9 queries spanning the full reference-+strength distribution; full 100-query sweep pending. xiaoyi entered+the leaderboard mid-April 2026 at 57.00, overtaking Grep as DRB #1+before hyperresearch took the top slot.Output: assets/benchmark.png"""@@ -14,31 +16,34 @@ import matplotlib.pyplot as pltimport numpy as npfrom matplotlib import patheffects-# (label, RACE overall score) — 6 entries, descending.+# (label, RACE overall score) — 7 entries, descending.# Numbers from the live DeepResearch-Bench leaderboard at# https://huggingface.co/spaces/muset-ai/DeepResearch-Bench-Leaderboard-# (snapshot 2026-04-13). hyperresearch score is a forward projection-# from the Q91 pilot (+2.08 over a 52.74 v1 baseline); full sweep pending.+# (snapshot 2026-04-29). hyperresearch number is the V8.3 stratified+# pilot mean across 9 queries; full 100-query sweep pending.entries = [- ("hyperresearch", 57.5), # projected- ("Grep Deep Research", 56.23), # DRB #1- ("Cellcog Max", 56.13), # DRB #2- ("nvidia-aiq", 55.95), # DRB #3 (Nemotron 3 + GPT 5.2)- ("Gemini 2.5 Pro Deep Research", 49.71), # DRB #21- ("OpenAI Deep Research", 46.45), # DRB #23+ ("hyperresearch", 57.77), # V8.3 stratified pilot (n=9)+ ("xiaoyi", 57.00), # NEW — current public DRB #1+ ("Grep Deep Research", 56.23), # DRB #2+ ("Cellcog Max", 56.13), # DRB #3+ ("nvidia-aiq", 55.95), # DRB #4 (Nemotron 3 + GPT 5.2)+ ("Gemini 2.5 Pro Deep Research", 49.71),+ ("OpenAI Deep Research", 46.45),]labels = [e[0] for e in entries]scores = [e[1] for e in entries]-# Color ramp: hyperresearch in electric coral (attention), leaderboard-# leaders in azure-teal (cool/credible), the two hyperscaler products in+# Color ramp: hyperresearch in electric coral (attention), xiaoyi in+# indigo as the recently-overtaken front-runner, the rest of the+# leaderboard in cool blues / teals, the two hyperscaler products in# warm amber/orange (distinguishable from leaders).colors = ["#FF4D6D", # hyperresearch — coral/electric red+ "#6C63FF", # xiaoyi — indigo (new front-runner, just overtaken)"#4361EE", # Grep Deep Research — deep blue"#2E9CCA", # Cellcog Max — azure- "#2EC4B6", # 1688AILab — teal+ "#2EC4B6", # nvidia-aiq — teal"#B892FF", # Gemini DR — lavender"#FFB627", # OpenAI DR — amber]@@ -121,7 +126,7 @@ for i, tick in enumerate(ax.get_xticklabels()):# clearly. Scores in this regime are compressed; 0-100 full scale would# flatten everything into identical-looking bars.ax.set_ylabel(- "RACE overall score (axis truncated at 40; max = 100)",+ "RACE overall score (50 is PhD level)",color=dim,fontsize=11,labelpad=10,@@ -150,8 +155,7 @@ ax.set_title(# Captionfig.text(0.5, 0.015,- "hyperresearch score projected from Q91 (+2.08 over v1 baseline); full 100-query sweep pending."- " · leaderboard snapshot: deepresearch-bench.github.io, 2026-04",+ "leaderboard snapshot: deepresearch-bench.github.io, 2026-04",color=dim,fontsize=9,style="italic",diff --git a/assets/banner.png b/assets/banner.pngindex 789582f..ec19f66 100644Binary files a/assets/banner.png and b/assets/banner.png differdiff --git a/assets/benchmark.png b/assets/benchmark.pngindex a670847..1a5048a 100644Binary files a/assets/benchmark.png and b/assets/benchmark.png differ