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

feat: ship the repo as a Claude Code plugin with a deep-research skill (#147)

Jordan Gibbs600ac2da6a24
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..b1c1d46
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,17 @@
+{
+ "name": "hyperresearch",
+ "description": "Claude Code marketplace for hyperresearch, a deep research skill and pipeline.",
+ "owner": {
+ "name": "Jordan Gibbs",
+ "url": "https://github.com/jordan-gibbs"
+ },
+ "plugins": [
+ {
+ "name": "hyperresearch",
+ "source": "./",
+ "description": "Deep research skill for Claude Code. Bootstraps the hyperresearch CLI and hands off to its 16-step research pipeline.",
+ "category": "research",
+ "homepage": "https://github.com/jordan-gibbs/hyperresearch"
+ }
+ ]
+}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..1ad78b4
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,13 @@
+{
+ "name": "hyperresearch",
+ "version": "0.11.1",
+ "description": "Deep research skill for Claude Code. Bootstraps the hyperresearch CLI and hands off to its 16-step research pipeline with a persistent, searchable source vault.",
+ "author": {
+ "name": "Jordan Gibbs",
+ "url": "https://github.com/jordan-gibbs"
+ },
+ "homepage": "https://github.com/jordan-gibbs/hyperresearch",
+ "repository": "https://github.com/jordan-gibbs/hyperresearch",
+ "license": "MIT",
+ "keywords": ["deep-research", "research", "claude-code", "skill", "citations", "research-agent"]
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6c4c763..ab59570 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
## [Unreleased]
+- **The repo is a Claude Code plugin marketplace.** `/plugin marketplace add jordan-gibbs/hyperresearch` then `/plugin install hyperresearch@hyperresearch` adds one skill, `deep-research`, at `skills/deep-research/SKILL.md`. It checks for the `hyperresearch` CLI, runs `hyperresearch install` in the current project, and hands off to `/hyperresearch`. It holds no pipeline steps; those still come from the Python package.
- Add scholarly metadata filters and metadata-only browsing to CLI and MCP search, including semantic filtering and a cache upgrade that preserves unchecked retraction status.
- **BEHAVIOR CHANGE — crawl4ai's headless browser verifies TLS certificates (#137).** crawl4ai defaults `BrowserConfig.ignore_https_errors` to True and launches Chromium with `--ignore-certificate-errors` on every start, so the provider `hpr install` switches a vault to fetched most HTML with verification off. Setting `ignore_https_errors = False` alone changes nothing (checked against a self-signed server on crawl4ai 0.8.6); the provider now also drops those launch flags, on both the plain launch and the login-profile (managed browser) launch, and refuses to start if a crawl4ai release moves the code it overrides. A refused certificate raises `CertVerificationError` naming the code (`ERR_CERT_AUTHORITY_INVALID`, ...) and the new opt-out, `[fetch] browser_verify_tls = false`. Before, it came back as an empty page and was reported as junk. As on the builtin and PDF lanes, the failure is final: no unverified retry, no escalation. In a batch it is a logged skip. The visible-window lane (`--visible` with a login profile) still ignores certificate errors, since some of the walled sites it serves have broken chains. Batch fetches also stopped mislabelling results: `arun_many` returns them in completion order, and they were paired with the requested URLs by position.
- **An OpenAlex outage no longer erases a known retraction.** Only OpenAlex reports retractions; when it errors, `lookup_metadata` falls through to Semantic Scholar, which answers "unknown". `sources score --fresh` (and the ship-time `sources retractions` sweep) wrote that unknown over a stored `is_retracted = 1`, so a retracted citation passed the gate. Unknown now keeps a stored retraction. A stored false is still replaced, since older versions wrote an unchecked false for every S2 result.
diff --git a/README.md b/README.md
index b217479..4d95428 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
<img width="1280" height="400" alt="hyperresearch-readme-hero-1280x400" src="https://github.com/user-attachments/assets/320680fc-bc56-4eac-9ec2-7ec46d4bde98" />
-<h3 align="center">The Most Powerful Deep Research Harness</h3>
+<h3 align="center">The Most Powerful Deep Research Harness: a Claude Code deep research skill</h3>
<p align="center">
<a href="https://pypi.org/project/hyperresearch/"><img src="https://img.shields.io/pypi/v/hyperresearch" alt="PyPI version"></a>
@@ -47,6 +47,17 @@ Then `/hyperresearch <anything>` in Claude Code.
>
> Power users: `hyperresearch install --global` makes `/hyperresearch` reachable from every Claude Code session anywhere, at the cost of ~15 lines in every session's system reminder. Per-project install (above) keeps unrelated CC sessions clean.
+### Install as a Claude Code plugin
+
+The repo is also a Claude Code plugin marketplace. The plugin ships one skill, `deep-research`, which checks for the `hyperresearch` CLI, runs `hyperresearch install` in the current project, and hands off to `/hyperresearch`. The pipeline still comes from the Python package, so you need `pip install hyperresearch` either way.
+
+```
+/plugin marketplace add jordan-gibbs/hyperresearch
+/plugin install hyperresearch@hyperresearch
+```
+
+Then ask for deep research in plain words, or run `/hyperresearch:deep-research <question>`. If Claude Code does not pick up the newly installed skills and subagents, restart it in the same directory and run `/hyperresearch <question>`.
+
---
## The 16-step research pipeline
diff --git a/skills/deep-research/SKILL.md b/skills/deep-research/SKILL.md
new file mode 100644
index 0000000..b4867cb
--- /dev/null
+++ b/skills/deep-research/SKILL.md
@@ -0,0 +1,63 @@
+---
+name: deep-research
+description: Deep research in Claude Code with hyperresearch. Use when the user asks for deep research, a research report, a literature review, or a multi-source analysis with verified citations. Checks that the hyperresearch CLI is installed, sets it up in the current project, then hands off to the /hyperresearch pipeline (a tier-adaptive 16-step pipeline with a persistent source vault). Not for quick lookups one or two searches can answer.
+---
+
+# Deep research with hyperresearch
+
+This skill is a bootstrap. The research pipeline itself is the `hyperresearch`
+skill plus 16 step skills and a set of subagents, which the `hyperresearch`
+Python package renders and installs into the project's `.claude/` directory.
+This file does not contain the pipeline. Do not try to run the research from
+here.
+
+## 1. Check the CLI
+
+Run:
+
+```bash
+hyperresearch --version
+```
+
+If the command is not found, stop and tell the user:
+
+> hyperresearch is not installed. Install it with `pip install hyperresearch`
+> (Python 3.11 to 3.14), then ask again.
+
+You may run `pip install hyperresearch` yourself only if the user says to.
+
+## 2. Install into this project
+
+If `.claude/skills/hyperresearch/SKILL.md` does not exist in the working
+directory, run:
+
+```bash
+hyperresearch install . --json
+```
+
+This creates the vault (`.hyperresearch/`, `research/`), adds a short block to
+`CLAUDE.md`, and installs the entry skill, the 16 step skills, the subagents
+and a PreToolUse hook under `.claude/`. It is safe to re-run; it no-ops on
+files that are already current.
+
+Tell the user in one line what was installed.
+
+## 3. Hand off
+
+Invoke the installed router with the user's research request, verbatim:
+
+```
+Skill(skill: "hyperresearch", args: "<the user's research request>")
+```
+
+From then on, follow the `hyperresearch` skill. It owns the query, the tier
+choice, and every step.
+
+If the `hyperresearch` skill is not available yet (Claude Code loads new
+subagents at session start, and some versions do the same for skills), tell
+the user that setup is done and ask them to restart Claude Code in this
+directory and run:
+
+```
+/hyperresearch <their research request>
+```