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
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
v0.8.3: lazy-install step skills per-project (#16)
Jordan Gibbs7e3c4c2da5fd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex fe4dcb7..15645b9 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,18 @@# Changelog+## [0.8.3] - 2026-04-29++### Quieter global install — step skills lazy-load per-project++Global install (`hyperresearch install --global`) used to write all 16 step skills to `~/.claude/skills/`, advertising them in the available-skills system reminder of every Claude Code session — ~3K tokens of noise on sessions where `/hyperresearch` is never used.++- **Global install now writes only the entry skill + agents to `~/.claude/`.** The 16 step skills (`hyperresearch-1-decompose` … `hyperresearch-16-readability-audit`) install per-project, lazily.+- **Entry skill bootstrap step 0** now also runs `hyperresearch install --steps-only .` if step skills aren't found in the project's `.claude/skills/`. First `/hyperresearch` invocation in a fresh project materializes the step skills there. Subsequent invocations no-op.+- **New `hyperresearch install --steps-only [PATH]`** flag — installs only the 16 step skills to `<path>/.claude/skills/`. Used by the bootstrap, also available manually.+- **Upgrade prune** — `hyperresearch install --global` removes any `hyperresearch-N-*` step-skill dirs left in `~/.claude/skills/` by 0.8.2-and-earlier global installs.++Net effect: sessions in projects that never use hyperresearch see only the entry skill + agent descriptions in their available-skills/agents lists. Step-skill noise is scoped to projects that actually use the tool.+## [0.8.2] - 2026-04-29### Global installdiff --git a/README.md b/README.mdindex 6c998c1..3732120 100644--- a/README.md+++ b/README.md@@ -26,8 +26,7 @@**Once, globally** (recommended) — `/hyperresearch` becomes available in every Claude Code session anywhere:```bash-pip install hyperresearch-hyperresearch install --global+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.diff --git a/pyproject.toml b/pyproject.tomlindex 0b35186..4037f66 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "hyperresearch"-version = "0.8.2"+version = "0.8.3"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__.pyindex 4880ca8..486f5b5 100644--- a/src/hyperresearch/__init__.py+++ b/src/hyperresearch/__init__.py@@ -1,3 +1,3 @@"""Hyperresearch — agent-driven research knowledge base."""-__version__ = "0.8.2"+__version__ = "0.8.3"diff --git a/src/hyperresearch/cli/install.py b/src/hyperresearch/cli/install.pyindex 7e2a3cc..72cd4ad 100644--- a/src/hyperresearch/cli/install.py+++ b/src/hyperresearch/cli/install.py@@ -18,18 +18,49 @@ def install(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).",+ help="Install Claude Code entry skill + agents to ~/.claude/ so /hyperresearch works in every Claude Code session anywhere. Skips vault init, CLAUDE.md, and the 16 step skills (those happen per-project on first /hyperresearch run).",+ ),+ steps_only: bool = typer.Option(+ False,+ "--steps-only",+ help="Install only the 16 step skills to <PATH>/.claude/skills/. Used internally by the entry skill bootstrap on first /hyperresearch invocation in a project. Not normally invoked by users.",),) -> None:"""Install hyperresearch: init vault + inject CLAUDE.md + install Claude Code hooks."""import sys- from hyperresearch.core.hooks import install_global_hooks, install_hooks+ from hyperresearch.core.hooks import (+ _install_hyperresearch_step_skills,+ 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.+ # Steps-only path: lazy install of the 16 step skills to a project's+ # .claude/skills/. Called by the entry skill's bootstrap on first+ # /hyperresearch in a project (after a global install). Cheap no-op+ # on subsequent invocations.+ if steps_only:+ target = Path(path).resolve()+ result = _install_hyperresearch_step_skills(target)+ if json_output:+ output(+ success({"steps_installed": result, "target": str(target)}, vault=None),+ json_mode=True,+ )+ return+ if result:+ console.print(f"[green]Step skills installed:[/] {target}/.claude/skills/")+ console.print(f" {result}")+ else:+ console.print(f"[dim]Step skills already installed at {target}/.claude/skills/[/]")+ return++ # Global install path: only the user-level Claude Code entry skill ++ # agents. No vault, no CLAUDE.md, no step skills — pure "make the+ # slash command available everywhere" mode. Step skills install+ # per-project, lazily, when the entry skill bootstrap calls+ # `hyperresearch install --steps-only .` on first invocation.if global_install:from hyperresearch.core.agent_docs import _resolve_executable@@ -57,8 +88,8 @@ def install("\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.[/]"+ "[dim]On first /hyperresearch run in a project, the vault, research/ folder, "+ "and the 16 step skills are created in that project's .claude/.[/]")returndiff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.pyindex 2b6c041..8fe17dc 100644--- a/src/hyperresearch/core/hooks.py+++ b/src/hyperresearch/core/hooks.py@@ -2984,11 +2984,20 @@ def install_global_hooks(home: Path | None = None, hpr_path: str = "hyperresearcClaude Code session, only ones that have a hyperresearch vault)- Vault init (handled per-project, on first /hyperresearch invocation)- CLAUDE.md injection (per-project)+ - **The 16 step skills**. Globally advertising 16 internal step+ skills would add ~3K tokens of system-reminder noise to every+ Claude Code session. Step skills install per-project, lazily,+ when the entry-skill bootstrap calls `hyperresearch install+ --steps-only .` on first /hyperresearch invocation. Sessions in+ unrelated projects see zero step-skill noise.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+ in every Claude Code session anywhere on the machine. The vault,+ research/, CLAUDE.md, and the 16 step skills all materialize in theproject root where Claude Code is running, on first invocation.++ Also prunes any hyperresearch-N-* step-skill dirs left in ~/.claude/skills/+ by older versions (≤0.8.2 used to install step skills globally)."""if home is None:home = Path.home()@@ -2997,7 +3006,6 @@ def install_global_hooks(home: Path | None = None, hpr_path: str = "hyperresearcfor 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),@@ -3013,6 +3021,7 @@ def install_global_hooks(home: Path | None = None, hpr_path: str = "hyperresearclambda: _install_draft_orchestrator_agent(home, hpr_path),lambda: _install_synthesizer_agent(home, hpr_path),lambda: _prune_retired_agents(home),+ lambda: _prune_global_step_skills(home),):result = installer()if result:@@ -3021,6 +3030,38 @@ def install_global_hooks(home: Path | None = None, hpr_path: str = "hyperresearcreturn actions+def _prune_global_step_skills(home: Path) -> str | None:+ """Remove hyperresearch-N-* step skill dirs from ~/.claude/skills/.++ Used by install_global_hooks to clean up after older versions (≤0.8.2)+ that installed step skills globally. Step skills now live per-project.+ """+ skills_root = home / ".claude" / "skills"+ if not skills_root.is_dir():+ return None++ pruned: list[str] = []+ for child in skills_root.iterdir():+ if not child.is_dir():+ continue+ # Match hyperresearch-<digit>-* (the 16 step skills) but not+ # the entry skill at .claude/skills/hyperresearch/+ name = child.name+ if not name.startswith("hyperresearch-"):+ continue+ suffix = name[len("hyperresearch-"):]+ if not suffix or not suffix[0].isdigit():+ continue+ for f in child.iterdir():+ f.unlink()+ child.rmdir()+ pruned.append(name)++ if not pruned:+ return None+ return f"Pruned {len(pruned)} global step-skill dirs (now per-project): {', '.join(pruned[:3])}{'...' if len(pruned) > 3 else ''}"++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.mdindex 9ffa9b6..ad49ae3 100644--- a/src/hyperresearch/skills/hyperresearch.md+++ b/src/hyperresearch/skills/hyperresearch.md@@ -74,11 +74,11 @@ Step 1 classifies the query into a `pipeline_tier` (`light` / `full`). The tierBefore 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.+0. **Auto-init if missing.** Two checks for the first-run-after-global-install case:+ - **Vault check.** If `.hyperresearch/` doesn't exist in the working directory, run `hyperresearch init . --json`. Creates the SQLite vault and `research/` directory.+ - **Step-skills check.** If `.claude/skills/hyperresearch-1-decompose/SKILL.md` doesn't exist relative to the working directory, run `hyperresearch install --steps-only . --json`. Installs the 16 step skill files needed by `Skill(skill: "hyperresearch-N-...")` calls in later steps.++ If either command fails because the binary isn't on PATH, tell the user to run `pip install hyperresearch` first. If both files already exist, both commands no-op cheaply — safe to run unconditionally.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.