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.3: lazy-install step skills per-project (#16)

Jordan Gibbs7e3c4c2da5fd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 install
diff --git a/README.md b/README.md
index 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.toml
index 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__.py
index 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.py
index 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/.[/]"
)
return
diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.py
index 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 = "hyperresearc
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 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 the
project 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 = "hyperresearc
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),
@@ -3013,6 +3021,7 @@ def install_global_hooks(home: Path | None = None, hpr_path: str = "hyperresearc
lambda: _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 = "hyperresearc
return 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.md
index 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 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.
+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.