Build citation-checked research reports in Codex. The skill orchestrates the research workflow, while the Hyperresearch engine fetches sources, saves notes and checks completion.
Install the skill once by copying the complete hyperresearch folder to your project's .agents/skills/hyperresearch, including its scripts and references. Open a new Codex chat in the folder where you want to keep the research and make a request such as:
Use $hyperresearch to investigate this question with a resumable, source-verified research pipeline: How do SQLite and PostgreSQL differ for an application that starts on one machine and later needs concurrent writers?
Codex follows the bundled skill workflow: it checks the pinned runtime, initializes a vault when needed, prepares the native procedures, roles and project-local Stop hook, then conducts the research. The skill includes runtime and Chromium installation commands. Later sessions reuse the runtime and the vault's saved state. Supply your question, output requirements, constraints and an optional budget in the request.
Preparation generates 18 procedures and 15 role configurations. The agent applies the selected tier's requirements for independent roles, drafts, critique, citations, source budgets and patch-only report updates. A full-tier run uses three drafts and four critics. The final report is saved to research/notes/final_report_<vault_tag>.md; check completion with hyperresearch run finish <vault_tag> --json and its passed: true result.
The configured scale profile (full or premier) is separate from the run tier (light, full or dissertation). Ask for a profile change before the next run. Request the dissertation tier explicitly.
Runtime setup requires Git and Python 3.11–3.14. New vaults use Crawl4AI and Chromium; Linux also needs Chromium's system libraries. For existing vaults, install the browser required by the selected provider. Configure credentials for the providers you select.
The runtime is kept outside the skill at ~/.codex/runtimes/hyperresearch/0.12.0-9c16854. Preflight returns its exact executable and Python paths. To choose a custom runtime location, set HYPERRESEARCH_RUNTIME_DIR to an absolute path in the Codex process's environment.
Use these commands when you want to prepare the runtime directly. This Windows PowerShell example starts in a project containing the installed .agents/skills/hyperresearch folder and resolves its own paths. On Linux and macOS, replace Scripts/python.exe with bin/python.
$skillPath = (Resolve-Path '.agents/skills/hyperresearch').Path
$runtimePath = if ($env:HYPERRESEARCH_RUNTIME_DIR) { $env:HYPERRESEARCH_RUNTIME_DIR } else { Join-Path $HOME '.codex/runtimes/hyperresearch/0.12.0-9c16854' }
$runtimePython = Join-Path $runtimePath 'Scripts/python.exe'
if (-not (Test-Path -LiteralPath $runtimePython)) { python -m venv $runtimePath }
& $runtimePython -m pip install -c (Join-Path $skillPath 'runtime-constraints.txt') 'hyperresearch[all] @ git+https://github.com/jordan-gibbs/hyperresearch.git@9c16854fed2d345a557e8759156a2ca5d02fa4f4'
& $runtimePython -m patchright install chromium
& $runtimePython (Join-Path $skillPath 'scripts/preflight.py') --cwd . --json --strictFor manual preparation of a new vault, start in the chosen research folder with the skill installed there. This block also works in a fresh PowerShell session with an existing runtime. Run init_vault.py once for a new vault; run prepare_codex.py for a new or existing vault. To change the scale profile before a run, add --profile full or --profile premier to the preparation command.
$skillPath = (Resolve-Path '.agents/skills/hyperresearch').Path
$runtimePath = if ($env:HYPERRESEARCH_RUNTIME_DIR) { $env:HYPERRESEARCH_RUNTIME_DIR } else { Join-Path $HOME '.codex/runtimes/hyperresearch/0.12.0-9c16854' }
$runtimePython = Join-Path $runtimePath 'Scripts/python.exe'
& $runtimePython (Join-Path $skillPath 'scripts/init_vault.py') --path . --json
& $runtimePython (Join-Path $skillPath 'scripts/prepare_codex.py') --path . --jsonThe CLI example resolves the runtime from a fresh session, fetches a source, reopens its note, extracts a citation and checks run status. The engine also provides scholarly discovery, search, claims, graph, export, import, indexing, embedding, watch, serve and MCP commands; see runtime capabilities.