# How to Install and Set Up Hyperresearch: Complete Setup Guide

> Learn how to install and set up Hyperresearch with this complete guide. Quickly install the package, create your vault, and activate the research pipeline for efficient knowledge management.

- Repository: [Jordan Gibbs/hyperresearch](https://github.com/jordan-gibbs/hyperresearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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.

```bash
pip install hyperresearch

```

As documented in the [README.md](https://github.com/jordan-gibbs/hyperresearch/blob/main/README.md#L34-L40), 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.

```bash
hyperresearch install

```

According to the source in [`src/hyperresearch/skills/hyperresearch.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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:

```bash
hyperresearch profile use premier

```

Profile configurations are stored in [`.hyperresearch/config.toml`](https://github.com/jordan-gibbs/hyperresearch/blob/main/.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](https://github.com/jordan-gibbs/hyperresearch/blob/main/README.md#L261-L266):

```bash

# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/.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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/.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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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.