English | 简体中文
Codex Autoresearch is the easiest way to turn the Karpathy autoresearch loop into a real Codex workflow on your own repo.
Instead of giving you a pile of prompts, it gives you a runner:
- one goal
- one measurable metric
- one Codex change at a time
- one verify step after every change
- one keep-or-revert decision logged to disk
If you want proof in under a minute:
autore start --demo --runIf you want to use it on your own repo:
autore startIf you want a visual control room instead of memorizing commands:
autore ui --open-browserIf you want the tool to prepare the repo and tell you exactly what to do next:
autore onboard --write-nightlyautore start is the default happy path.
It will:
- detect whether your repo looks like Python, Node, or generic
- create
autoresearch.tomlif it does not exist yet - run
autore doctor --fix - establish a baseline metric
- run a bounded Codex loop
- keep improvements and revert non-improvements
During long runs, logs are written to .autoresearch/runs/iteration-XXXX/.
This project is for the moment when you want Codex to improve a repository mechanically instead of vaguely.
Examples:
- increase pytest coverage
- reduce bundle size
- expand collected tests
- improve a build output metric
- keep trying small changes until a measurable number gets better
autore start --demo --runautore startautore onboardautore ui --open-browserautore nightly --forceautore watch --follow
autore watch --stream stdout --follow
autore watch --stream resultsautore start --resume
autore run --resume --iterations 5flowchart LR
A["Run autore start"] --> B["Auto-create config if missing"]
B --> C["Doctor fixes obvious setup gaps"]
C --> D["Baseline metric"]
D --> E["Codex makes one change"]
E --> F["Verify + Guard"]
F --> G{"Metric improved?"}
G -- "Yes" --> H["Keep commit"]
G -- "No" --> I["Revert commit"]
H --> J["Write results.tsv"]
I --> J
If you do not want to think about setup details, use:
autore onboard --write-nightlyIt will:
- run doctor with auto-fix enabled
- make sure
.autoresearch/is ignored - infer a sensible preset
- explain the best use case for this repo
- print the exact next commands to copy
- optionally generate
.github/workflows/autoresearch-nightly.yml
If you prefer clicking over remembering commands, run:
autore ui --open-browserThe local UI gives you:
- a repo health dashboard
- one-click setup repair
- one-click onboarding and nightly workflow generation
- a live task queue with streaming terminal output
- a built-in config editor with save button
- a metric chart and run timeline
- recent results without opening TSV files by hand
[research]
goal = "Increase test coverage from 72 to 90"
metric = "coverage percent"
direction = "higher"
verify = "pytest --cov=src 2>&1 | grep TOTAL"
scope = ["src/**", "tests/**"]
guard = "pytest"
iterations = 10[research]
goal = "Reduce bundle size below 200 KB without breaking tests"
metric = "bundle size kb"
direction = "lower"
verify = "npm run build 2>&1 | grep 'First Load JS'"
scope = ["src/**"]
guard = "npm test"
iterations = 10Generate the workflow:
autore nightly --forceOr let onboarding do it for you:
autore onboard --write-nightlyThe generated GitHub Actions workflow:
- runs every day at
01:00 UTC - prepares the repo with
autore doctor --fix - runs a bounded resume loop
- uploads
.autoresearch/results.tsvand run logs as artifacts
See docs/nightly.md and examples/nightly.yml.
autoresearch.toml: repo-specific loop config.autoresearch/results.tsv: iteration-by-iteration ledger.autoresearch/runs/...: stdout/stderr logs for each Codex run- automatic keep/discard behavior based on your metric
- optional guard command to block regressions
Most autoresearch repos stop at prompts.
This one gives you a runnable outer loop for Codex:
autore startfor the shortest happy pathautore onboardfor first-time repo setupautore nightlyfor scheduled GitHub runsautore watchfor long-task visibilityautore run --resumefor continuing an existing branch