Skip to content

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

chart + banner refresh for launch (#11)

Jordan Gibbs951ccc09f085
diff --git a/README.md b/README.md
index 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 hyperresearch
hyperresearch 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.
```bash
hyperresearch search "ion-trap gate fidelity" -j # Full-text search
@@ -102,7 +104,7 @@ 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. 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:
```bash
hyperresearch 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.py
new file mode 100644
index 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.py
index 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 plt
import numpy as np
from 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(
# Caption
fig.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.png
index 789582f..ec19f66 100644
Binary files a/assets/banner.png and b/assets/banner.png differ
diff --git a/assets/benchmark.png b/assets/benchmark.png
index a670847..1a5048a 100644
Binary files a/assets/benchmark.png and b/assets/benchmark.png differ