# Autoresearch

Stateful validator-gated research loop with native-hook persistence

- Repository: https://github.com/Yeachan-Heo/oh-my-codex (33693 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Yeachan-Heo/oh-my-codex --skill autoresearch -g -a claude-code -y`
Codex: `npx skills add Yeachan-Heo/oh-my-codex --skill autoresearch -g -a codex -y`
Cursor: `npx skills add Yeachan-Heo/oh-my-codex --skill autoresearch -g -a cursor -y`
Gemini CLI: `npx skills add Yeachan-Heo/oh-my-codex --skill autoresearch -g -a gemini-cli -y`

## Description

Stateful validator-gated research loop with native-hook persistence

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Autoresearch

Autoresearch is the skill-first replacement for the deprecated `omx autoresearch` command.
It keeps the useful measured-research loop, but it now runs as a native-hook stateful workflow instead of a direct CLI or tmux launch surface.

## Boundary with planning research

Use `$autoresearch` when the research output itself is a bounded deliverable that must pass an explicit validator. Do not recommend it for ordinary pre-planning docs lookup or general best-practice checks; use `$best-practice-research` for that. If `$autoresearch` is intentionally run before architecture planning, its approved artifact should feed evidence into `$ralplan`; it should not become a final architecture/component unless the user explicitly asks for ongoing research automation.

## Use when
- You want a Ralph-ish persistent research loop
- The task should keep nudging until explicit validation evidence exists
- You want init-time choice between script validation and prompt+architect validation

## Do not use when
- You want the old `omx autoresearch` command surface (hard-deprecated)
- You want detached tmux or split-pane launch parity
- You have not decided the validation regime yet

## Core contract
1. **Init chooses validation mode.** Pick exactly one:
   - `mission-validator-script`
   - `prompt-architect-artifact`
2. **Persist mode state** in `.omx/state/.../autoresearch-state.json` including:
   - `validation_mode`
   - `completion_artifact_path`
   - `mission_validator_command` **or** `validator_prompt`
   - optional `output_artifact_path`
3. **Completion is artifact-gated.** The loop does not stop because the model says “done”, because a stop hook fired once, or because several turns were no-ops.
4. **Direct CLI launch is gone.** Use `$deep-interview --autoresearch` for intake and `$autoresearch` for execution.

## Completion artifact contract

### `mission-validator-script`
The completion artifact must exist and record a passing validator result, for example:

The rest: https://github.com/Yeachan-Heo/oh-my-codex/blob/HEAD/plugins/oh-my-codex/skills/autoresearch/SKILL.md