Hyper Research

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>, or any case not explicitly single-path) → both paths in parallel (Codex + Claude), producing two artifacts that share one slug.
• ONLY if the user EXPLICITLY asks for Codex only / no Claude → Codex path alone.
• ONLY if the user EXPLICITLY asks for Claude only / Claude-native / no-Codex / a Claude second opinion → Claude path alone.
• If the intent is genuinely unclear → treat it as the default (both paths in parallel). Only narrow to a single path on an unambiguous explicit request.

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:

1. 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.

2. 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.

3. Launch both in ONE message, both backgrounded — neither blocks, so the lead stays free while the two multi-minute operations run:

   • The researcher agent 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: true with timeout: 600000: 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.

4. Once both have completed, write and report the artifacts. Read the bridge task's output file and parse the JSON line in it (ignore the trailing [exited with code N] marker), then rm -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 -claude suffix; the frontmatter slug: 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.

5. 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>.md so /hyperclaude:hyper-plan-review can find it later.

Codex path (single — explicit request only)

1. Resolve the task description as described in Path selection above.

2. Write the resolved task description to a temp file using the Write tool (not the Bash tool — this avoids shell quoting). Pick a path under the system temp dir; for example: /tmp/hyperclaude-task-<unix-timestamp>.txt. Save the task as plain text; no escaping needed.

3. Run the bridge in research mode using the Bash tool with run_in_background: true and timeout: 600000:

   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.

4. After the bridge task completes, clean up the temp file:

   rm -f "<temp file path>"
   

5. The bridge prints a single JSON line to stdout. Read the 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.

6. Integrate the file's findings into your subsequent plan. When you write a plan, save it under .hyperclaude/plans/<timestamp>-<slug>.md so /hyperclaude:hyper-plan-review can 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.

1. Derive <slug> from the resolved task with the same rule as hyper-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.

2. Get <timestamp> (UTC — matches the bridge's artifact filename convention):

   date -u +%Y%m%d-%H%M
   

3. Create the artifact directory and resolve the artifact path:

   mkdir -p .hyperclaude/research
   

   Base path: .hyperclaude/research/<timestamp>-<slug>-claude.md (the -claude suffix 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/-3 collision suffixing) — and the frontmatter slug: line is the bare key with an empty value: slug: (key, colon, single space, nothing after — NOT slug: "").

4. Dispatch the researcher agent 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.

5. Collect the always-present frontmatter values with one short Node one-liner (keeps cwd/git-head JSON-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}))'
   

6. Write the artifact with the Write tool to the path from step 3. Frontmatter is ONLY the keys below, in this order (do NOT byte-match renderFrontmatter(), do NOT add Codex-only conditional keys like codex-thread-id, and do NOT author plugin-version — the PostToolUse stamp hook adds it after 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.

7. 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.