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

v0.8.2: hyperresearch install --global (#15)

Jordan Gibbsb05bc9a0847c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f7ed8dc..fe4dcb7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
# Changelog
+## [0.8.2] - 2026-04-29
+
+### Global install
+
+- **`hyperresearch install --global`** writes the Claude Code skills + agents to `~/.claude/` so `/hyperresearch` is available in every Claude Code session anywhere on the machine, with no per-project setup. Skips vault init and CLAUDE.md injection (those happen automatically per-project on first `/hyperresearch` invocation).
+- New `install_global_hooks()` in `core/hooks.py` that targets `~/.claude/` and skips the PreToolUse hook script (would otherwise fire on every Claude Code session).
+- Entry skill bootstrap now auto-runs `hyperresearch init .` if no vault exists in cwd, so the global-install workflow is fully seamless: pip install + `hyperresearch install --global` once, then `/hyperresearch` works everywhere and materializes the vault + `research/` folder + `CLAUDE.md` in whatever project root you're in on first use.
+
## [0.8.1] - 2026-04-29
### Surface cleanup
diff --git a/README.md b/README.md
index efc76d9..6c998c1 100644
--- a/README.md
+++ b/README.md
@@ -23,8 +23,20 @@
## Install
+**Once, globally** (recommended) — `/hyperresearch` becomes available in every Claude Code session anywhere:
+
+```bash
+pip install hyperresearch
+hyperresearch install --global
+```
+
+The vault, `research/` folder, and project-level `CLAUDE.md` are created automatically in the project root the first time you type `/hyperresearch <query>` in a Claude Code session.
+
+**Per-project** (if you'd rather opt in explicitly per repo):
+
```bash
pip install hyperresearch
+cd your-project
hyperresearch install
```
diff --git a/pyproject.toml b/pyproject.toml
index 9303e41..0b35186 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "hyperresearch"
-version = "0.8.1"
+version = "0.8.2"
description = "Claude Code harness for disciplined, adversarially-audited deep research with full provenance."
readme = "README.md"
license = "MIT"
diff --git a/src/hyperresearch/__init__.py b/src/hyperresearch/__init__.py
index e20216d..4880ca8 100644
--- a/src/hyperresearch/__init__.py
+++ b/src/hyperresearch/__init__.py
@@ -1,3 +1,3 @@
"""Hyperresearch — agent-driven research knowledge base."""
-__version__ = "0.8.1"
+__version__ = "0.8.2"
diff --git a/src/hyperresearch/cli/install.py b/src/hyperresearch/cli/install.py
index 90d6704..7e2a3cc 100644
--- a/src/hyperresearch/cli/install.py
+++ b/src/hyperresearch/cli/install.py
@@ -14,13 +14,54 @@ def install(
path: str = typer.Argument(".", help="Path to install in"),
name: str = typer.Option("Research Base", "--name", "-n", help="Vault name"),
json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+ global_install: bool = typer.Option(
+ False,
+ "--global",
+ "-g",
+ help="Install Claude Code skills + agents to ~/.claude/ so /hyperresearch works in every Claude Code session anywhere. Skips vault init and CLAUDE.md (those happen per-project on first /hyperresearch run).",
+ ),
) -> None:
"""Install hyperresearch: init vault + inject CLAUDE.md + install Claude Code hooks."""
import sys
- from hyperresearch.core.hooks import install_hooks
+ from hyperresearch.core.hooks import install_global_hooks, install_hooks
from hyperresearch.core.vault import Vault, VaultError
+ # Global install path: only the user-level Claude Code skills + agents.
+ # No vault, no CLAUDE.md, no project-level state — pure "make the slash
+ # command available everywhere" mode.
+ if global_install:
+ from hyperresearch.core.agent_docs import _resolve_executable
+
+ hpr_path = _resolve_executable()
+ home = Path.home()
+ hook_actions = install_global_hooks(home, hpr_path=hpr_path)
+
+ if json_output:
+ output(
+ success(
+ {"global": True, "home": str(home), "hooks_installed": hook_actions},
+ vault=None,
+ ),
+ json_mode=True,
+ )
+ return
+
+ console.print(f"[green]Global install:[/] {home}/.claude/")
+ if hook_actions:
+ for action in hook_actions:
+ console.print(f" {action}")
+ else:
+ console.print("[dim]All skills and agents already installed.[/]")
+ console.print(
+ "\n[bold]Ready.[/] /hyperresearch is now available in every Claude Code session."
+ )
+ console.print(
+ "[dim]On first /hyperresearch run in a project, the vault and research/ folder "
+ "are created in that project's root.[/]"
+ )
+ return
+
root = Path(path).resolve()
# First-time install in an interactive terminal → run the setup TUI instead
diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.py
index 9fcbcfe..2b6c041 100644
--- a/src/hyperresearch/core/hooks.py
+++ b/src/hyperresearch/core/hooks.py
@@ -2976,6 +2976,51 @@ def install_hooks(vault_root: Path, hpr_path: str = "hyperresearch") -> list[str
return actions
+def install_global_hooks(home: Path | None = None, hpr_path: str = "hyperresearch") -> list[str]:
+ """Install Claude Code skills + agents globally under ~/.claude/.
+
+ Unlike `install_hooks`, this skips:
+ - The PreToolUse vault-check hook (don't want it firing on every
+ Claude Code session, only ones that have a hyperresearch vault)
+ - Vault init (handled per-project, on first /hyperresearch invocation)
+ - CLAUDE.md injection (per-project)
+
+ The result: pip install + this once, and `/hyperresearch` is available
+ in every Claude Code session anywhere on the machine. The actual
+ research artifacts (vault, research/, CLAUDE.md) materialize in the
+ project root where Claude Code is running, on first invocation.
+ """
+ if home is None:
+ home = Path.home()
+
+ actions = []
+
+ for installer in (
+ lambda: _install_hyperresearch_skill(home),
+ lambda: _install_hyperresearch_step_skills(home),
+ lambda: _install_researcher_agent(home, hpr_path),
+ lambda: _install_loci_analyst_agent(home, hpr_path),
+ lambda: _install_depth_investigator_agent(home, hpr_path),
+ lambda: _install_source_analyst_agent(home, hpr_path),
+ lambda: _install_dialectic_critic_agent(home, hpr_path),
+ lambda: _install_instruction_critic_agent(home, hpr_path),
+ lambda: _install_depth_critic_agent(home, hpr_path),
+ lambda: _install_width_critic_agent(home, hpr_path),
+ lambda: _install_patcher_agent(home, hpr_path),
+ lambda: _install_polish_auditor_agent(home, hpr_path),
+ lambda: _install_readability_reformatter_agent(home, hpr_path),
+ lambda: _install_corpus_critic_agent(home, hpr_path),
+ lambda: _install_draft_orchestrator_agent(home, hpr_path),
+ lambda: _install_synthesizer_agent(home, hpr_path),
+ lambda: _prune_retired_agents(home),
+ ):
+ result = installer()
+ if result:
+ actions.append(result)
+
+ return actions
+
+
def _write_hook_script(vault_root: Path, hpr_path: str) -> Path:
"""Write the hook JS script to .hyperresearch/hook.js."""
hook_dir = vault_root / ".hyperresearch"
diff --git a/src/hyperresearch/skills/hyperresearch.md b/src/hyperresearch/skills/hyperresearch.md
index 07d0ff0..9ffa9b6 100644
--- a/src/hyperresearch/skills/hyperresearch.md
+++ b/src/hyperresearch/skills/hyperresearch.md
@@ -74,6 +74,12 @@ Step 1 classifies the query into a `pipeline_tier` (`light` / `full`). The tier
Before you invoke any step skill, do this:
+0. **Auto-init if no vault exists.** Check whether `.hyperresearch/` exists in the working directory. If not, the user installed hyperresearch globally (`hyperresearch install --global`) and this is the first `/hyperresearch` invocation in this project. Run:
+ ```bash
+ hyperresearch init . --json
+ ```
+ This creates the SQLite vault, the `research/` directory, and a project-level `CLAUDE.md` with the hyperresearch workflow blurb. If this fails because the binary isn't on PATH, tell the user to run `pip install hyperresearch` first. If `.hyperresearch/` already exists, skip this step.
+
1. **Resolve the canonical research query.** Order of precedence:
- If `research/prompt.txt` exists (legacy harness / wrapped run), read it. Its contents are the canonical research query. GOSPEL.
- Otherwise, use the user's verbatim prompt as the canonical research query.