How to Install and Set Up Hyperresearch: Complete Setup Guide

TLDR: Run pip install hyperresearch to fetch the package, then hyperresearch install to generate the SQLite-backed vault, register the 16 Claude Code skills, and activate the research pipeline.

Hyperresearch is a Python-based deep-research harness that converts Claude Code prompts into multi-step, adversarially-audited research reports. According to the jordan-gibbs/hyperresearch source code, setting up the system requires installing the PyPI distribution and then initializing a persistent vault that indexes fetched sources. The following guide walks through the complete installation process using the exact commands and file paths defined in the repository.

Step 1: Install the Core Package

Begin by installing Hyperresearch from PyPI. This pulls the core library and CLI tools required to orchestrate the research pipeline.

pip install hyperresearch

As documented in the README.md, this command provides the hyperresearch entry-point script and the underlying Python modules. The package includes the skill templates located in src/hyperresearch/skills/, which the installer will copy into your project in the next step.

Step 2: Initialize the Project Vault

After the package is present, run the project-level installer. This command creates the local storage layer and integrates with Claude Code.

hyperresearch install

According to the source in src/hyperresearch/skills/hyperresearch.md (lines 86-90), this step performs four critical actions:

• Creates a hidden .hyperresearch/ directory—the vault—which stores all fetched notes as markdown files backed by a SQLite index.
• Installs the 16 step-skill files under .claude/skills/, including templates for decomposition, width sweeps, and readability audits.
• Injects the required Claude Code hooks that trigger the pipeline.
• Verifies that the vault exists; if missing, it automatically executes hyperresearch init . to bootstrap the research/ folder and database.

The vault persists across sessions, allowing the system to deduplicate sources and maintain cached research state.

Step 3: Configure Profiles and Optional Providers

Hyperresearch ships with a default full profile and supports optional gears like premier for higher-capacity runs (~100-130 sources). You can also enable web-provider integrations that require additional dependencies.

Switch Research Gears

To upgrade from the default profile to the premier tier:

hyperresearch profile use premier

Profile configurations are stored in .hyperresearch/config.toml, which tracks the active gear, web-provider selection, and optional API keys.

Install Web Provider Extras

For projects requiring stealthy PDF extraction or specialized search, install optional provider packages as noted in README.md:

# Headless browser for PDF extraction

pip install "hyperresearch[crawl4ai]"

# Or other providers like exa, tavily, parallel, serply

pip install "hyperresearch[exa]"

Global Installation (Optional)

To make the /hyperresearch entry skill available in every Claude Code session without per-project setup:

hyperresearch install --global

This appends approximately 15 lines of configuration to your global Claude Code settings.

Step 4: Set Up Authenticated Crawling (Optional)

For research requiring access to gated content (LinkedIn, Twitter), run the interactive setup TUI:

hyperresearch setup

This utility logs into target sites and stores browser credentials in the escalation lane, allowing the pipeline to perform authenticated crawling when necessary.

Step 5: Verify the Installation

Confirm that the vault, skills, and CLI are properly linked:

hyperresearch run status -j

This outputs JSON-formatted pipeline status, indicating whether the SQLite vault is reachable and the 16 step-skills are registered. Once verified, initiate a research query:

hyperresearch run "What are the latest advances in quantum error correction?"

The command triggers the full 16-step pipeline—decompose, width sweep, source ranking, adversarial audit—and writes the final report to research/runs/<vault_tag>/final_report.md.

Summary

• Two-phase setup: First pip install hyperresearch for the package, then hyperresearch install for the vault and skills.
• Vault architecture: The .hyperresearch/ directory stores markdown notes with a SQLite index, created automatically in the project root.
• Skill injection: The installer copies 16 step-templates into .claude/skills/ and registers Claude Code hooks per src/hyperresearch/skills/hyperresearch.md.
• Optional enhancements: Use --global for system-wide availability, hyperresearch profile use premier for higher source limits, and pip install "hyperresearch[crawl4ai]" for headless browser support.
• Verification: Run hyperresearch run status -j to check pipeline health before executing research queries.

Frequently Asked Questions

What is the difference between pip install hyperresearch and hyperresearch install?

pip install hyperresearch installs the Python package and CLI binary from PyPI to your environment. hyperresearch install is a project-level command that creates the .hyperresearch/ vault directory, initializes the SQLite database, and copies the 16 skill files into .claude/skills/. You must run both: the first provides the tool, the second configures your specific project directory.

Do I need API keys to use Hyperresearch?

The base installation does not require API keys for the default full profile. However, optional web-provider integrations—such as exa, tavily, or crawl4ai—require corresponding API keys stored in .hyperresearch/config.toml. These providers enhance search capabilities but are not mandatory for core functionality.

How do I switch from the default profile to the premier gear?

Execute hyperresearch profile use premier after completing the initial installation. This updates .hyperresearch/config.toml to use the premier gear, which expands the source limit from the default to approximately 100-130 sources per research run. You can switch back to the default with hyperresearch profile use full.

What happens if the vault directory is missing when I run a query?

If the .hyperresearch/ vault is deleted or corrupted, the entry skill defined in src/hyperresearch/skills/hyperresearch.md automatically detects the absence and runs hyperresearch init . to recreate the directory structure and SQLite index. You can also manually regenerate the vault with hyperresearch init . --json if the automatic detection fails.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}