The Problem

Deep research tools produce one-off reports that die in a chat window. Every session starts from zero, re-fetching sources and re-verifying citations. For anyone doing sustained research—a dissertation, a market analysis, a technical survey—that's wasted time and duplicated effort. The vault should persist and compound across sessions.

What This Does

hyperresearch is a Python package that turns Claude Code into a tier-adaptive, 16-step deep research pipeline. One prompt produces an adversarially-audited report with verified source provenance. Every source lands in a persistent, searchable vault (src/hyperresearch/core/vault.py), so the next session reuses prior work before fetching anything new.

The pipeline is orchestrated by skill files in src/hyperresearch/skills/—each step is a markdown procedure loaded only when that step runs. Core logic lives in src/hyperresearch/core/ (config, sync, notes, escalation, hooks), with CLI commands in src/hyperresearch/cli/ and an MCP server in src/hyperresearch/mcp/server.py for programmatic access.

How It Is Wired

Execution starts at src/hyperresearch/__main__.py, which routes to cli/main.py. The init command reaches 20 functions and touches the database via conn.execute in core/vault.py. The fetch command (cli/fetch.py) is the deepest path: it reaches 91 functions, makes outbound network calls, writes to the database, and computes SHA-256 hashes for deduplication—all within a few hops from the entry point.

The blast radius is concentrated in a few modules. core/vault.py is called from 46 files and owns the database connection. cli/_output.py (output function) is called from 99 places—change its signature and nearly the entire CLI breaks. core/sync.py's compute_sync_plan (43 callers) and execute_sync (40 callers) are the sync backbone, handling file/database writes plus hashing.

The MCP server (mcp/server.py) exposes fetch_url, search_notes, and create_note as tool entry points. Notably, fetch_url uses string-interpolated SQL (see Code Health), which is a security concern for any untrusted input.

How To Use It

Setup: This is a Python package with a pyproject.toml. Install with pip or uv:

pip install hyperresearch
# or: uv pip install hyperresearch

Configuration: No environment variables are documented. Configuration is handled via TOML profiles in core/config.py and core/profiles.py—run hyperresearch install to scaffold the vault and profiles.

Running it:

cd your-project
pip install hyperresearch && hyperresearch install
# Then in Claude Code: /hyperresearch <your research query>

The CLI also offers hyperresearch fetch, hyperresearch search, hyperresearch serve, and hyperresearch run commands. The MCP server runs via hyperresearch mcp or directly through src/hyperresearch/mcp/server.py.

Real-World Use

For a dissertation: run hyperresearch install in a project directory, then invoke /hyperresearch with a chapter-level question. The pipeline decomposes it, fetches 100–300 sources (tier-dependent), verifies every citation, and writes a chapter with provenance links into the vault. The next day, a follow-up query reuses the vault before fetching anything new—no re-researching what's already been covered.

Code Health & Issues

Static analysis (measured, not opinion) found 56 findings: 8 high, 48 medium.

  • High - Duplicated code blocks (164 repeated 6-line blocks across 39 files, e.g., cli/archive.py, cli/assets.py). Extract shared helpers.
  • High - Deep nesting (max indentation depth 10 in cli/fetch.py, cli/lint.py, tests/test_core/test_escalation.py). Flatten with guard clauses.
  • High - Oversized files (1456 lines in cli/lint.py, 30 functions in core/hooks.py). Split by responsibility.
  • Med - File opens without context managers (5 instances, e.g., serve/server.py).
  • Med - Broad exception handling (13 instances across cli/__init__.py, cli/fetch.py).
  • Med - High branching density (161 branch points over 504 lines in cli/fetch.py).

SDLC findings from the code health audit:

  • High - Unpinned GitHub Actions (pypa/gh-action-pypi-publish@release/v1)—pin to commit SHAs.
  • High - No lockfile—non-reproducible builds; declared ranges reach known CVEs (pydantic, crawl4ai, jinja2).
  • High - SQL string interpolation in mcp/server.py—use bound parameters.
  • Med - No permissions declaration on GITHUB_TOKEN in CI.
  • Med - No dependency vulnerability scan in CI.
  • Med - No Dependabot/Renovate configured.
  • Low - No job timeouts in workflows.

Tests are present (58 files) and CI runs via GitHub Actions. No Dockerfile, no committed secrets.

The Bottom Line

This is a serious research tool with real depth—the 16-step pipeline, citation verification, and persistent vault are genuinely useful. The architecture is sound but the code needs hardening: lockfile, dependency pinning, and SQL parameterization are non-negotiable before production use. For a researcher who lives in Claude Code and needs verifiable, accumulating research, this is worth adopting—just budget time for the security fixes first.