Codex Autoresearch

Aim. Iterate. Arrive.

Autonomous, measurable experimentation for Codex.

English · 中文 · 日本語 · 한국어 · Français · Deutsch · Español · Português · Русский

---

Tell Codex what measurable result you want. Codex inspects the repository, confirms the experiment with you, changes one thing, verifies it, keeps improvements, reverts failures, and repeats until the target is reached.

Autoresearch works for test failures, coverage, type errors, warnings, latency, binary size, reproducible security findings, and any other outcome a command can measure.

Quick Start

Install from Codex:

$skill-installer install https://github.com/leo-lilinxiao/codex-autoresearch

Open a clean Git repository with Full Access:

codex --dangerously-bypass-approvals-and-sandbox

Then invoke the skill:

You:   $codex-autoresearch
       Reduce `python3 scripts/score.py` error_count to 0.

Codex: Baseline: 5
       Target: 0 (lower is better)
       Scope: src/
       Verify: python3 scripts/score.py, JSON key error_count
       Guard: none
       Run in foreground or background?

You:   Background. Go.

Codex launches the confirmed run. No Codex configuration changes or special prompt syntax are required.

See Installation for manual and development installs.

The Loop

inspect evidence
      |
change one focused thing
      |
commit and measure
      |
      +-- improved + guard passes --> keep
      |
      +-- otherwise ---------------> revert
      |
append an audit event
      |
repeat until target

The control script owns commits, verification, rollback, and state. Codex owns the hypotheses and code changes.

Foreground And Background

	Foreground	Background
Runs in	Current Codex task	Detached controller
Continuation	Official Codex Goal	One codex exec worker per iteration
Best for	Watching and steering live	Long or overnight runs
Control	Codex Goal pause/resume	Ask $codex-autoresearch for status, stop, or resume

Foreground and background use the same experiment rules. A run uses one mode at a time. Foreground continuation uses a Codex Goal; background continuation belongs to the detached controller.

What Gets Confirmed

Before the first write, Codex shows:

• the goal and numeric target;
• repository-relative paths it may change;
• the metric command and explicit parser;
• an optional regression guard;
• foreground or background mode;
• an optional iteration limit.

Initialization requires a clean named Git branch. One run manages one repository.

Codex reuses choices and approval you have already given. Once the experiment is confirmed, it keeps working without asking you to approve each iteration.

Results

Run artifacts live in autoresearch-results/ and stay uncommitted:

Path	Purpose
run.json	Immutable confirmed configuration
events.jsonl	Append-only baseline, iteration, stop, and completion history
logs/	Full metric, guard, and background worker output
runtime.json	Background process state
runtime.log	Background controller lifecycle events
report.html	Optional, regenerated visual snapshot

events.jsonl is the state history. Missing, malformed, contradictory, or partial state is an error; the skill never guesses a result from old files or conversational memory.

Review Results