Codex Autoresearch

Install

npx skillfoxx add skills/codex-autoresearch

npx skills add leo-lilinxiao/codex-autoresearch --skill codex-autoresearch -a claude-code -y

npx skills add leo-lilinxiao/codex-autoresearch --skill codex-autoresearch -a cursor -y

npx skills add leo-lilinxiao/codex-autoresearch --skill codex-autoresearch -a github-copilot -y

npx skills add leo-lilinxiao/codex-autoresearch --skill codex-autoresearch -a codex -y

npx skills add leo-lilinxiao/codex-autoresearch --skill codex-autoresearch -a gemini-cli -y

npx skills add leo-lilinxiao/codex-autoresearch --skill codex-autoresearch -a cline -y

npx skills add leo-lilinxiao/codex-autoresearch --skill codex-autoresearch -a roo -y

npx skills add leo-lilinxiao/codex-autoresearch --skill codex-autoresearch -a opencode -y

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

This is third-party code. Review the repository files before installing.

What it does

The skill gives Codex a discipline for autonomous optimization of a repository toward a chosen numeric metric. The user names a measurable result, for example zero test failures, fewer warnings, lower latency or binary size, and the skill repeats a loop: change one thing, measure with a verify command, keep the improvement or revert with git revert. A control script owns commits, verification, rollback and the event history, while Codex owns hypotheses and code changes. Before the first write the skill confirms the goal, edit scopes, the metric command, an optional regression guard and the run mode, foreground or background. A complete status is set only when the retained metric reaches the confirmed target, and the full history is written to autoresearch-results.

Who it is for. For developers and quality engineers who need autonomous iterative optimization of code toward a measurable goal.

Example request

Reduce error_count from python3 scripts/score.py to zero, only touch src, run in background

Limitations

It works only with Codex and needs Python 3.11 or newer, git and a configured author identity. One run is one repository, one metric and one clean named branch; without git the skill does not work, since git is the experiment memory and the rollback boundary. The metric command must exit successfully and print one finite number or a JSON object with an explicitly named key. Background runs default to full access because each step creates or reverts a commit.

How to disable. Remove the codex-autoresearch folder from the skills directory, usually .agents/skills in the project or ~/.agents/skills. The autoresearch-results directory in the project repository can be removed separately.

Security check

• Autonomously changes code and creates and reverts git commits
• Runs arbitrary metric commands and defaults to full access

README in short

The README describes an autonomous system for Codex that iteratively improves a repository toward a numeric target, inspired by Karpathy's autoresearch idea. The user names a measurable result, Codex inspects the repository, confirms the experiment, changes one thing, verifies and keeps a success or reverts a failure. Installation goes through $skill-installer or manual copying into the skills directory, and a run opens on a clean git branch with full access. Run artifacts live in autoresearch-results: an immutable config, an event log, logs and an optional HTML report. Every trial is a commit, any failed check is reverted with git revert, and a strict safety model stops the run on out-of-scope edits or failures. MIT licensed.

SKILL.md

---
name: codex-autoresearch
description: "Run repeated, measured Git experiments toward a numeric target; keep improvements and revert failures. Use for autonomous optimization or managing an autoresearch run, not one-shot edits."
metadata:
  short-description: "Run measurable autonomous experiments"
---

# Codex Autoresearch

Improve a repository through repeated, reversible experiments:

`hypothesize -> change -> measure -> learn -> keep or revert -> repeat`

Codex chooses hypotheses and makes code changes. The control script owns measurement, commits, rollback, and the event history.

## Respond To The Request

Resolve `<control>` to this skill's own `scripts/autoresearch.py`; do not assume it is installed in the target repository.

For a status or results request, run the corresponding command directly:

| Request | Command |
|---|---|
| Status | `python3 <control> status --repo <repo>` |
| History | `python3 <control> history --repo <repo>` |
| TSV export | `python3 <control> history --repo <repo> --format tsv` |
| HTML report | `python3 <control> report --repo <repo>` |

## Experiment Boundary

- One run owns one Git repository, one numeric metric, one confirmed target, and approved path scopes.
- Use `finish` to finalize each coherent experiment.
- Only a verified target can mean `complete`; an iteration limit, error, or external blocker has its own status.

Related