Self-directed iterative research skill for Codex that continuously cycles through modify, verify, retain or discard, and repeat until a measurable goal is reached.

Codex Autoresearch Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. Codex Autoresearch is a Codex skill that runs an autonomous modify→verify→keep/revert loop on your codebase. You describe a measurable goal in one sentence; Codex confirms the plan, then iterates unattended — every improvement stacks in git, every failure reverts automatically — until interrupted or a cap is reached. Inspired by Karpathy's autoresearch concept, generalized beyond ML training to any software metric. Installation Option A — manual copy into your project: Option B — Codex skill installer: The skill lives at .agents/skills/codex autoresearch/ inside your project. No config file is required before first use. How to Activate Open Codex in your project directory and prefix your goal with $codex autoresearch : Codex will: 1. Scan the repo and infer scope, metric, verify command, and guard command. 2. Present a confirmation summary — reply go (or correct anything). 3. Run the loop unattended until you interrupt it or the goal is met. You never write config. Codex infers everything. Confirmation Flow Before the loop starts Codex always shows what it found and asks you to confirm. Example exchange: Up to five confirmation rounds are possible. After that, Codex proceeds. The Loop (internals) The loop runs unbounded unless you say Iterations: N during confirmation. Dual Gate Verification Two commands serve distinct purposes: Gate Purpose Fails means Verify Did the target metric improve? Change discarded, reverted Guard Did anything else break? Change reworked (up to 2 attempts), then reverted Guard files are never modified by the loop. Example verify + guard pair for a Python coverage run: Example for TypeScript type cleanup: Modes Codex maps your sentence to one of seven modes automatically — you never pick a mode explicitly. loop — iterate toward a measurable target (default) plan — turn a vague goal into a validated loop config Codex will interview you (p95 latency vs throughput? which endpoint?) and produce a ready to run loop config. fix — repair errors until count reaches zero debug — evidence driven root cause hunting Each iteration tests one falsifiable hypothesis. Codex presents evidence, not guesses. security — read only STRIDE + OWASP audit ship — readiness verification and release gating exec — one shot execution with no loop Inline Configuration (optional) You can override defaults inline during the confirmation step — no file edits needed: Phrase Effect Iterations: 20 Cap the loop at 20 iterations Parallel: 3 Test 3 hypotheses concurrently per round Guard: npm test Override the inferred guard command Verify: <command Override the inferred verify command Scope: src/api/ Restrict changes to a subdirectory Example during confirmation: Cross Run Learning At the end of each iteration Codex writes a structured lesson to .agents/skills/codex autoresearch/lessons.md : On session resume Codex reads this file first. Each new run benefits from prior runs. To resume an interrupted run: Codex re reads the lessons file, checks git state, re establishes the baseline, and continues. Parallel Experiments Request parallel mode during confirmation or at any time: Codex runs four hypotheses concurrently, keeps the best result, discards the rest. Useful when hypothesis space is large. Pivot Protocol If the loop stalls, escalation happens automatically: Consecutive discards Action 3 REFINE — narrow hypothesis, try smaller atomic changes 5 PIVOT — change strategy entirely 2 PIVOTs Web search — Codex fetches external references to unstick itself You are never asked for permission during escalation. The loop continues. Real Code Examples Example 1 — TypeScript any elimination (Python verify script) If you want a custom verify script instead of a one liner: Tell Codex during confirmation: Example 2 — pytest coverage loop (Python) Example 3 — bundle size loop (Node.js project) Example 4 — lint warning count (any language) Unattended Runs For overnight or long runs, ensure Codex CLI approval settings do not interrupt git commit or git revert commands. The simplest option is to run in a disposable or sandboxed repo clone: Results accumulate in git history. Pull the winning commits back to your main repo when done: Session Artifacts File Contents .agents/skills/codex autoresearch/lessons.md Structured lessons from every iteration .agents/skills/codex autoresearch/results.log Full per iteration log (metric value, kept/reverted, elapsed) .agents/skills/codex autoresearch/session.json Current session state for resume These files persist across Codex sessions. Delete them to start fresh. Troubleshooting Loop reverts every change: Verify command may be returning a non numeric value. Test it manually: bash c "<your verify command " should print a single number. Metric direction may be wrong. Confirm Direction: lower or Direction: higher during setup. Guard fires on unrelated files: Narrow scope: Scope: src/specific module/ Or tell Codex explicitly: Do not touch tests/ during confirmation. Session resume picks up wrong baseline: Delete session.json to force a fresh baseline: rm .agents/skills/codex autoresearch/session.json Parallel mode produces merge conflicts: Codex handles this internally via the pivot protocol, but if it gets stuck, reduce parallelism: Parallel: 2 Codex asks questions mid loop: This means a guard crash produced ambiguous output. Pre empt it by specifying Guard: <command true if guard failures should be non fatal, or by giving Codex fuller sandbox permissions so it can run git commands freely. Loop hits PIVOT but makes no progress: Supply a seed hypothesis during confirmation: Hint: try tree shaking unused imports first Or run plan mode first to produce a richer hypothesis list before switching to loop . Quick Reference

codex-autoresearch-loop