Deep research with hyperresearch skill
Deep research with hyperresearch, for Claude Code and OpenAI Codex.
by jordan-gibbs·MIT license·★ 3,803 Stars on the repo·GitHub ↗
npx degit jordan-gibbs/hyperresearch/skills/deep-research#main ~/.claude/skills/deep-research-2Checked ·commit main
Files of Deep research with hyperresearch
Show the full text118 lines
Deep research with hyperresearch
This skill is a bootstrap. The research pipeline itself is an entry skill plus
16 step procedures and a set of subagents, which the hyperresearch Python
package renders and installs into the project. This file does not contain the
pipeline. Do not try to run the research from here, and do not answer the
research question from your own knowledge: the pipeline is the deliverable.
1. Check the CLI
Run:
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. Pick your branch
You know which agent you are. Follow exactly one branch.
- Claude Code (you have
SkillandTasktools): section 3A. - OpenAI Codex (you edit files with
apply_patch, spawn custom agents, and skills are invoked as$name): section 3B.
If you genuinely cannot tell, look at the working directory: a .codex/ or
.agents/ directory and no .claude/ means Codex; the reverse means Claude
Code. Still unsure: ask the user which one they are using.
3A. Claude Code
If .claude/skills/hyperresearch/SKILL.md does not exist in the working
directory, run:
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.
Then 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>
3B. OpenAI Codex
If .agents/skills/hyperresearch/SKILL.md does not exist in the working
directory, run:
hyperresearch install . --target codex --json
This creates the vault (.hyperresearch/, research/), adds a short block to
AGENTS.md, and installs the entry skill at .agents/skills/hyperresearch/,
the step procedures under .hyperresearch/codex/steps/, the custom agents
under .codex/agents/, and a Stop hook in .codex/hooks.json. It is safe to
re-run. Tell the user in one line what was installed.
If the install (or any later hyperresearch fetch) fails with a permission or
network error, the session is sandboxed read-only or offline. Stop and tell
the user to restart Codex with a writable workspace and network access, for
example:
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true
Then hand off. Codex discovers skills when a session starts, so a skill installed a moment ago may not be listed yet. The robust path is to read the entry skill directly and follow it:
- Read
.agents/skills/hyperresearch/SKILL.mdin full (for examplecat .agents/skills/hyperresearch/SKILL.md). - Follow it with the user's research request, verbatim, as the query. It is
the same procedure
$hyperresearch <request>would load. It owns the query, the tier choice, and every step, and each step tells you which procedure file under.hyperresearch/codex/steps/to read next.
If $hyperresearch already appears in your skill list, invoking it with the
request is equivalent. In later sessions the user can start a run directly
with $hyperresearch <question>.
Two things differ from Claude Code, and the entry skill covers both: there is no browser lane (blocked fetches stay queued and are listed for the user at the end), and the Stop hook, once Codex trusts the project's hooks, will not let the session finish while a run is mid-pipeline.
| 1 | |
| 2 | name deep-research |
| 3 | description Deep research with hyperresearch, for Claude Code and OpenAI Codex. 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 for the agent you are running in, 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. |
| 4 | license MIT |
| 5 | compatibility Requires Python 3.11+ and the hyperresearch CLI (pip install hyperresearch), plus network access for fetching sources. Works in Claude Code and OpenAI Codex CLI; under Codex the session needs a writable workspace with network enabled. |
| 6 | |
| 7 | |
| 8 | # Deep research with hyperresearch |
| 9 | |
| 10 | This skill is a bootstrap. The research pipeline itself is an entry skill plus |
| 11 | 16 step procedures and a set of subagents, which the `hyperresearch` Python |
| 12 | package renders and installs into the project. This file does not contain the |
| 13 | pipeline. Do not try to run the research from here, and do not answer the |
| 14 | research question from your own knowledge: the pipeline is the deliverable. |
| 15 | |
| 16 | ## 1. Check the CLI |
| 17 | |
| 18 | Run: |
| 19 | |
| 20 | |
| 21 | hyperresearch --version |
| 22 | |
| 23 | |
| 24 | If the command is not found, stop and tell the user: |
| 25 | |
| 26 | > hyperresearch is not installed. Install it with `pip install hyperresearch` |
| 27 | > (Python 3.11 to 3.14), then ask again. |
| 28 | |
| 29 | You may run `pip install hyperresearch` yourself only if the user says to. |
| 30 | |
| 31 | ## 2. Pick your branch |
| 32 | |
| 33 | You know which agent you are. Follow exactly one branch. |
| 34 | |
| 35 | **Claude Code** (you have `Skill` and `Task` tools): section 3A. |
| 36 | **OpenAI Codex** (you edit files with `apply_patch`, spawn custom agents, |
| 37 | and skills are invoked as `$name`): section 3B. |
| 38 | |
| 39 | If you genuinely cannot tell, look at the working directory: a `.codex/` or |
| 40 | `.agents/` directory and no `.claude/` means Codex; the reverse means Claude |
| 41 | Code. Still unsure: ask the user which one they are using. |
| 42 | |
| 43 | ## 3A. Claude Code |
| 44 | |
| 45 | If `.claude/skills/hyperresearch/SKILL.md` does not exist in the working |
| 46 | directory, run: |
| 47 | |
| 48 | |
| 49 | hyperresearch install . --json |
| 50 | |
| 51 | |
| 52 | This creates the vault (`.hyperresearch/`, `research/`), adds a short block to |
| 53 | `CLAUDE.md`, and installs the entry skill, the 16 step skills, the subagents |
| 54 | and a PreToolUse hook under `.claude/`. It is safe to re-run; it no-ops on |
| 55 | files that are already current. Tell the user in one line what was installed. |
| 56 | |
| 57 | Then invoke the installed router with the user's research request, verbatim: |
| 58 | |
| 59 | |
| 60 | Skill(skill: "hyperresearch", args: "<the user's research request>") |
| 61 | |
| 62 | |
| 63 | From then on, follow the `hyperresearch` skill. It owns the query, the tier |
| 64 | choice, and every step. |
| 65 | |
| 66 | If the `hyperresearch` skill is not available yet (Claude Code loads new |
| 67 | subagents at session start, and some versions do the same for skills), tell |
| 68 | the user that setup is done and ask them to restart Claude Code in this |
| 69 | directory and run: |
| 70 | |
| 71 | |
| 72 | /hyperresearch <their research request> |
| 73 | |
| 74 | |
| 75 | ## 3B. OpenAI Codex |
| 76 | |
| 77 | If `.agents/skills/hyperresearch/SKILL.md` does not exist in the working |
| 78 | directory, run: |
| 79 | |
| 80 | |
| 81 | hyperresearch install . --target codex --json |
| 82 | |
| 83 | |
| 84 | This creates the vault (`.hyperresearch/`, `research/`), adds a short block to |
| 85 | `AGENTS.md`, and installs the entry skill at `.agents/skills/hyperresearch/`, |
| 86 | the step procedures under `.hyperresearch/codex/steps/`, the custom agents |
| 87 | under `.codex/agents/`, and a Stop hook in `.codex/hooks.json`. It is safe to |
| 88 | re-run. Tell the user in one line what was installed. |
| 89 | |
| 90 | If the install (or any later `hyperresearch fetch`) fails with a permission or |
| 91 | network error, the session is sandboxed read-only or offline. Stop and tell |
| 92 | the user to restart Codex with a writable workspace and network access, for |
| 93 | example: |
| 94 | |
| 95 | |
| 96 | codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true |
| 97 | |
| 98 | |
| 99 | Then hand off. Codex discovers skills when a session starts, so a skill |
| 100 | installed a moment ago may not be listed yet. The robust path is to read the |
| 101 | entry skill directly and follow it: |
| 102 | |
| 103 | Read `.agents/skills/hyperresearch/SKILL.md` in full (for example |
| 104 | `cat .agents/skills/hyperresearch/SKILL.md`). |
| 105 | Follow it with the user's research request, verbatim, as the query. It is |
| 106 | the same procedure `$hyperresearch <request>` would load. It owns the |
| 107 | query, the tier choice, and every step, and each step tells you which |
| 108 | procedure file under `.hyperresearch/codex/steps/` to read next. |
| 109 | |
| 110 | If `$hyperresearch` already appears in your skill list, invoking it with the |
| 111 | request is equivalent. In later sessions the user can start a run directly |
| 112 | with `$hyperresearch <question>`. |
| 113 | |
| 114 | Two things differ from Claude Code, and the entry skill covers both: there is |
| 115 | no browser lane (blocked fetches stay queued and are listed for the user at |
| 116 | the end), and the Stop hook, once Codex trusts the project's hooks, will not |
| 117 | let the session finish while a run is mid-pipeline. |
| 118 |
Discussion
Alternatives
Scientific critical thinkingEvaluate scientific claims and evidence quality. Use for assessing experimental design validity, identifying biases and confounders, applying evidence grading frameworks (GRADE, Cochrane Risk of Bias), or teaching critical analysis. Best for understanding evidence quality, identifying flaws. For formal peer review writing use peer-review.
Academic research synthesizerAcademic research synthesis specialist. Use PROACTIVELY for comprehensive research on academic topics, literature reviews, technical investigations, and well-cited analysis combining multiple sources. <example>Context: A podcast episode needs a segment grounded in peer-reviewed evidence with formal citations. user: "Research the current state of transformer efficiency techniques for the episode, with proper academic citations." assistant: "I'll use the academic-research-synthesizer agent to search arXiv and Semantic Scholar, extract full-text findings via WebFetch, and produce a cited literature synthesis with confidence levels." <commentary>Use academic-research-synthesizer (not comprehensive-researcher) when the episode segment needs peer-reviewed sourcing, formal citation format, and explicit confidence tagging rather than general-purpose multi-source coverage.</commentary></example> <example>Context: The episode-orchestrator has routed a "literature review" request for a technical deep-dive segment. user: "Summarize the research landscape on federated learning privacy guarantees." assistant: "I'll invoke academic-research-synthesizer to systematically search academic sources, note peer-review status per source, and synthesize consensus vs. open debates."</example>Academic researcherAcademic research specialist for scholarly sources, peer-reviewed papers, and academic literature. Use PROACTIVELY for research paper analysis, literature reviews, citation tracking, and academic methodology evaluation. <example>Context: The research-orchestrator has kicked off Phase 4 parallel research on 'efficacy of intermittent fasting' and needs peer-reviewed evidence. user: "Find the academic evidence on intermittent fasting outcomes." assistant: "I'll use the academic-researcher agent to search Semantic Scholar, PubMed, and OpenAlex for peer-reviewed studies and write structured findings to academic-research.md." <commentary>The request is specifically for scholarly/peer-reviewed evidence rather than general web coverage or code, so academic-researcher (not web-researcher or technical-researcher) is the right specialist.</commentary></example> <example>Context: The user wants a literature review comparing methodologies across studies on a topic. user: "Can you review the literature on transformer model interpretability and identify research gaps?" assistant: "Let me invoke the academic-researcher agent to pull foundational and recent papers, extract methodologies, and surface open research gaps." <commentary>Literature review, methodology extraction, and research-gap identification are core academic-researcher capabilities, distinct from technical-researcher's focus on code repositories and implementations.</commentary></example>Browse more free Claude skills or everything in Product.