hyperresearch

CLI Tool

jordan-gibbs/hyperresearch

Deep research agent for Claude Code with a persistent, searchable source vault.

Overview

Turns Claude Code into a deep research agent with a tier-adaptive 16-step pipeline: hundreds of sources, adversarial critics, and verified citations. Every source lands in a persistent markdown-plus-SQLite vault that future runs reuse, with crash resume and scholarly search built in.

README Preview

\n\nThe Most Powerful Deep Research Harness\n\n\n  \n  \n  \n  \n\n\n---\n\n**Hyperresearch turns Claude Code into a deep research agent: one that currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally).** 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.\n\n\n  \n\n\nForward-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.\n\n## Why it wins\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **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.\n- **Paywalled papers get read, not skimmed.** A closed paper normally enters a vault as a 1,500-character

FAQ (3)

Troubleshooting
How to fix path traversal vulnerability where `run init` accepts `../../x` vault tag and scaffolds outside the vault?

Vault.run_dir() and init_run join the vault_tag onto research/runs/ without validation, so tags like ../../x or absolute paths escape the vault. Fix it the same way as the --tag traversal in #114: resolve the joined path and require it to sit under research/runs/, rejecting the tag with a clear error otherwise. A simpler alternative is to restrict the tag to the slug pattern [A-Za-z0-9_.-]+ at the CLI boundary, blocking / and .. segments entirely. Note the fix touches every run subcommand since they all resolve the tag the same way.

GitHub Issue #116
Troubleshooting
Why does hyperresearch quote-integrity lint report false 'hallucinated quote' errors and block run finish with blocked_on verify?

Root cause (hyperresearch v0.10.0): in cli/lint.py (_check_quote_integrity), the span regex _QUOTE_SPAN_RE = re.compile(r'["“]([^"“”]{20,600})["”]') enforces a 20-character minimum. Any genuinely quoted phrase shorter than 20 chars (e.g. "TVL", "reasonable use") fails to match at all; its closing quote is then misread as a new *opening* quote and paired with the next quote character hundreds of characters later, producing one giant false 'hallucinated' span containing ordinary prose. Fix (patch the tool): replace the regex with a non-greedy match with no hard floor — r'["“]([^"“”]{1,600}?)["”]' — and let the existing if len(quote.split()) < 5: continue check skip verification of short spans instead of relying on regex length for filtering. Workaround (report-side, no code change): locate every quoted span under 20 characters (script that sequentially pairs " marks and flags spans <20 chars), then either italicize genuine short terms-of-art (*Low Security* instead of "Low Security") or merge adjacent short quotes from contiguous source text into one longer verbatim quote (e.g. combine five short label fragments into a single 90+ char quoted span) until run finish passes.

GitHub Issue #120
Troubleshooting
Why do hyperresearch skill commands fail with 'run: command not found' or '$HPR' not found errors?

In hyperresearch 0.11.1, 14 of the 19 installed step skills under .claude/skills/ invoke the CLI as $HPR, but the HPR variable is never defined — not in the environment, not in .claude/settings.json, and not anywhere in the package. With HPR unset, $HPR expands to an empty string, so a command like $HPR run finish <vault_tag> --json becomes run finish ... and the shell reports run: command not found (a shell error, not a CLI error). Workarounds: 1) Export the variable yourself pointing at the installed binary: export HPR="$(command -v hyperresearch)" (add it to your shell profile or the agent's environment). 2) Or replace $HPR in the installed skills with the resolved absolute CLI path — the same path the installer already bakes into CLAUDE.md (shown as **CLI path: /path/to/hyperresearch**) and into all agent prompts. For example: grep -rl '\$HPR' .claude/skills/ | xargs sed -i "s|\$HPR|/path/to/hyperresearch|g". Verify with bash -c 'unset HPR; $HPR run status -j' before the fix (fails) and /path/to/hyperresearch run status -j after (works).

GitHub Issue #133