hyper-research
Skill5 starsChanged 48 days agoMITView on GitHub
Use when starting a non-trivial task and want prior-art, pitfalls, or recommendations before designing. Also when the user invokes /hyperclaude:hyper-research. Runs Codex and Claude in parallel by default, producing two artifacts in .hyperclaude/research/.
In this repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cc-changelogSkill
- codex-changelogSkill
- hyper-autoSkill
- hyper-code-reviewSkill
- hyper-docs-loopSkill
- hyper-docs-reviewSkill
- hyper-docs-syncSkill
- hyper-implement-loopSkill
- hyper-implementSkill
- hyper-interviewSkill
- hyper-memorySkill
- hyper-plan-loopSkill
- hyper-plan-reviewSkill
- hyper-planSkill
- hyper-recapSkill
- hyper-setupSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
When the request doesn't clearly ask for one path, run both.
- Distinctive: line 34
All cases first resolve the task description the same way:
- Distinctive: line 36
If the invocation argument is non-empty, that is the task description.
- Distinctive: line 37
If empty, fall back to the user's most recent build/implement intent in this conversation.
- Distinctive: line 66
Write the resolved task description with the Write tool (not the Bash tool — this avoids shell quoting) to a file in the session …
- Very specific: line 68
Run the bridge in research mode using the Bash tool with run_in_background: true and timeout: 7200000:
- Distinctive: line 76
After the bridge task completes, clean up the temp file:
- Distinctive: line 100
Create the artifact directory and resolve the artifact path:
- Very specific: line 119
Write the artifact with the Write tool to the path from step 3.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
hyper-research
Pre-implementation research gate. By default runs both the Codex research path and the Claude research path in parallel, producing two artifacts (.hyperclaude/research/<timestamp>-<slug>.md from Codex and .hyperclaude/research/<timestamp>-<slug>-claude.md from Claude) that share one frontmatter slug:; you read them and integrate findings into your next planning step. A single path runs only on explicit user request.
When to use
- User typed
/hyperclaude:hyper-research <task>. - You're about to start substantial new work and want a parallel Codex + Claude research context dump.
Skip when:
- The task is a small fix or rename.
- A recent research file (within ~30 min) already covers this task.
How to invoke
--resume is not supported (deferred — research is not iterative).
Invocation argument: $ARGUMENTS
Path selection
Two research paths exist (Codex and Claude). Pick by reading the user's intent — this is a plain-language rule, not a flag/token/$ARGUMENTS grammar:
- Default (a normal
/hyperclaude:hyper-research <task>) → both paths in parallel (Codex + Claude), producing two artifacts that share one slug. - The user asks for Codex only / no Claude → Codex path alone.
- The user asks for Claude only / Claude-native / no-Codex / a Claude second opinion → Claude path alone.
- When the request doesn't clearly ask for one path, run both.
All cases first resolve the task description the same way:
- If the invocation argument is non-empty, that is the task description.
- If empty, fall back to the user's most recent build/implement intent in this conversation. If none exists, ask the user to describe the task and stop.
Default: both paths in parallel
This is the default. Run the Codex and Claude research paths concurrently so the two multi-minute operations overlap:
- Resolve the task description (as in Path selection), derive
<slug>(Claude-path rule, step 1 below), and get<timestamp>once — these are shared by both artifacts. - Write the Codex task to a temp file with the Write tool (avoids shell quoting), as the Codex path step 2 below describes — this must land before the bridge launches.
Launch both in ONE message, both backgrounded — neither blocks, so the lead stays free while the two multi-minute operations run:
- The
researcheragent via the Agent tool,subagent_type: hyperclaude:researcher, in return-body mode, using the same prompt contract as the Claude path step 4 below (Task verbatim + required section structure). - The bridge via the Bash tool,
run_in_background: truewithtimeout: 7200000:node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" research --task-file "<temp file path>". It writes.hyperclaude/research/<timestamp>-<slug>.md.
Both deliver their result as a completion notification. End the turn and let them run; answer the user if they ask something else meanwhile.
- The
- Once both have completed, write and report the artifacts.
Readthe bridge task's output file and parse the JSON line in it (ignore the trailing[exited with code N]marker), thenrm -f "<temp file path>".- Codex
{"ok":true,"path":"..."}→ the Codex artifact is on disk at that path. - Codex
{"ok":false,"error":"..."}→ surface the error to the user. Do NOT pretend the Codex artifact was produced. - Researcher returned a body → write the Claude artifact with the Write tool to
.hyperclaude/research/<timestamp>-<slug>-claude.md, using the SAME frontmatter block + one-liner as in Claude path (single — explicit request only) steps 5–6. The ONLY difference from the single-Claude case is the filename's-claudesuffix; the frontmatterslug:stays<slug>(identical to the Codex artifact — this is the canonical trace key). - Researcher errored or returned an empty body → SKIP writing the Claude artifact.
- Exactly one side succeeded → report it as a PARTIAL result and continue using only what succeeded. Both failed → report full failure to the user and stop.
- Codex
- Report BOTH artifact paths to the user (Codex artifact + Claude artifact). Read both and integrate BOTH into your subsequent plan. When you write a plan, save it under
.hyperclaude/plans/<timestamp>-<slug>.mdso/hyperclaude:hyper-plan-reviewcan find it later.
Codex path (single — explicit request only)
- Resolve the task description as described in Path selection above.
- Write the resolved task description with the Write tool (not the Bash tool — this avoids shell quoting) to a file in the session scratchpad, outside the repo. Save the task as plain text; no escaping needed.
Run the bridge in research mode using the Bash tool with
run_in_background: trueandtimeout: 7200000:node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" research --task-file "<temp file path>"The lead stays free to answer the user while Codex runs; end the turn and wait for the completion notification.
After the bridge task completes, clean up the temp file:
rm -f "<temp file path>"- The bridge prints a single JSON line to stdout.
Readthe completed task's output file and parse that line (ignore the trailing[exited with code N]marker).- On
{"ok":true,"path":"..."}— read the file with the Read tool. - On
{"ok":false,"error":"..."}— surface the error to the user; do not pretend research happened.
- On
- Integrate the file's findings into your subsequent plan. When you write a plan, save it under
.hyperclaude/plans/<timestamp>-<slug>.mdso/hyperclaude:hyper-plan-reviewcan find it later.
Claude path (single — explicit request only)
This path runs Claude-native research via the researcher agent. It uses WebFetch against KNOWN URLs only — it is not web-search parity with the Codex --search bridge mode. If the user needs broad live web search, route them to the Codex path instead.
- Derive
<slug>from the resolved task with the same rule ashyper-plan: lowercase, ASCII only, alphanumerics + hyphen, first 5 words of the task joined by-. Example: "Add OAuth login to the API" →add-oauth-login-to-the. Get
<timestamp>(UTC — matches the bridge's artifact filename convention):date -u +%Y%m%d-%H%MCreate the artifact directory and resolve the artifact path:
mkdir -p .hyperclaude/researchBase path:
.hyperclaude/research/<timestamp>-<slug>-claude.md(the-claudesuffix is how the Claude artifact coexists with the Codex one when both ran). If it exists, append-2,-3, … before the extension until free.- No-ASCII-slug fallback (mirrors the bridge): if slug derivation yields no ASCII characters (e.g. an all-Korean topic), the filename is timestamp +
-claude—.hyperclaude/research/<timestamp>-claude.md(with the same-2/-3collision suffixing) — and the frontmatterslug:line is the bare key with an empty value:slug:(key, colon, single space, nothing after — NOTslug: "").
- No-ASCII-slug fallback (mirrors the bridge): if slug derivation yields no ASCII characters (e.g. an all-Korean topic), the filename is timestamp +
- Dispatch the
researcheragent with the Agent tool,subagent_type: hyperclaude:researcher, in return-body mode (the agent returns the report markdown; it does not write files) — it runs backgrounded, so end the turn and resume at step 5 on its completion notification. The prompt MUST include:- Task — the resolved task description, verbatim.
- Required section structure — the report must use exactly these headings, in this order:
### Prior Art,### Pitfalls,### Recommendations,### Open Questions.
Collect the always-present frontmatter values with one short Node one-liner (keeps
cwd/git-headJSON-quoted the same way the bridge's renderer does):node -e 'const c=require("child_process");let h;try{h=c.execSync("git rev-parse HEAD").toString().trim();}catch(e){h="unknown";}console.log(JSON.stringify({generated:new Date().toISOString(),cwd:process.cwd(),gitHead:h}))'Write the artifact with the Write tool to the path from step 3. Its frontmatter is exactly the keys below, in this order — the PostToolUse stamp hook adds
plugin-versionafter the write:--- mode: research task: |- <task, each line 2-space indented> slug: <slug> generated: <generated ISO from the one-liner> codex-version: claude template-version: 1 cwd: <JSON-quoted cwd from the one-liner> git-head: <JSON-quoted gitHead from the one-liner> codex-resume-status: fresh --- # Research: <task> <researcher agent body verbatim>For the no-ASCII-slug fallback, the
slug:line is the bare empty form described in step 3.- Tell the user the artifact path and that this was Claude-native research (no Codex). Then integrate the findings into your subsequent plan as in the Codex path step 6.
Output contract
A research file has YAML frontmatter followed by markdown sections (Prior Art / Pitfalls / Recommendations / Open Questions). Do not modify the file.
The default (parallel) run produces a Codex + Claude pair: .hyperclaude/research/<timestamp>-<slug>.md (Codex) and .hyperclaude/research/<timestamp>-<slug>-claude.md (Claude). Both files carry an identical frontmatter slug: — that shared slug is the canonical trace key, not the filename. A single-path run produces only the one corresponding file.
Every research file has the same always-present frontmatter keys (mode, task, slug, generated, plugin-version, codex-version, template-version, cwd, git-head, codex-resume-status) and the same section structure. plugin-version is present on both, but by different means: the bridge writes it into the Codex artifact, while the Claude artifact gets it from the PostToolUse stamp hook post-write (so it lands as the first frontmatter key, not mid-block). The Codex artifact's codex-version is the Codex CLI version and it may add Codex-only conditional keys (e.g. codex-thread-id; codex-input-tokens, codex-cached-input-tokens, codex-output-tokens, codex-reasoning-output-tokens — each emitted independently when Codex reported that token field in usage); the Claude artifact's codex-version is claude and it omits those conditional keys. Downstream consumers match on frontmatter slug: and may find BOTH files of a pair.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

