# Codex Autoresearch runs a measured edit loop and hands back a patch with evidence > Codex Autoresearch is a Codex plugin that treats optimization as a repeatable experiment: you approve a contract with a metric, checks, an edit scope and a budget, and the loop measures a baseline before trying candidates. Its own documentation is careful to claim no improvement over ordinary Codex, because no model driven comparison has been run. **TheGreenCedar/codex-autoresearch** — A codex plugin for running optimization loops inside a codebase. It is useful when you have a measurable target and many possible changes to try: test runtime, build speed, bundle size, model loss, Lighthouse scores, memory use, query latency, or any other metric you can print from a script. - Repository: https://github.com/TheGreenCedar/codex-autoresearch - Stars: 835 · Forks: 58 - Language: TypeScript - License: Apache-2.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/thegreencedar-codex-autoresearch ## Optimization as an experiment, not as a request Codex Autoresearch describes itself as a plugin for running optimization loops inside a codebase, and the framing matters. It is not asking a model to make the code faster. It asks you to define a measurement, a correctness check, an edit boundary and a budget, and then it runs a loop that records a baseline before it tries anything. The stated use cases are the ones with a number attached: test runtime, build speed, bundle size, model loss, Lighthouse scores, memory use, query latency, or any other metric you can print from a script. The README is blunt about what is out of scope. Reviews, documentation, product research and one-off fixes normally stay ordinary Codex work. Architecture reviews, documentation, UX, product study, open-ended research, taste and one-shot fixes all take a different path. That boundary is the design. The tool is for the case where several small attempts are more likely to teach you something than one large rewrite, which is a different bet from asking an agent to optimise something once. Version 3.0 widened the scope in one direction. Alongside the benchmark path there is support for investigations where you know the outcome you want but have not settled on a method. You accept the objective, allowed changes, evidence requirements and budget once, and preparation, failed attempts, repairs, confirmation and delivery all draw on that same allowance. Goals without a numeric metric can use explicit conditions and counterexamples instead. The loop is described as inspired by karpathy/autoresearch and pi-autoresearch, and this version is built around Codex, local repositories and ordinary reviewable Git work. ## The contract is reviewed before anything runs The unit of work is a contract, and you approve it before setup or execution. The setup step prepares an experiment contract for explicit acceptance, and it has a fixed set of parts: goal, repository and checkout, typed metric semantics, evaluator, independent checks, scope, noise, keep and stop rules, and budgets. That list is the whole safety model in one sentence. Scope says which files may change. Checks say what must remain correct. Keep and stop rules say when a candidate is worth keeping and when the loop ends. Budget says how much wall clock time or how many attempts you are spending. The starting point contract in the README shows how concrete this is in practice. ```bash /goal @Codex Autoresearch run a measured loop to reduce parser runtime. Benchmark: node bench/parser.mjs Metric: seconds (s), lower is better Checks: node --test tests/parser.test.mjs Scope: src/parser.mjs Protect bench/parser.mjs and tests/parser.test.mjs. Measure two baselines and repeat each candidate before a keep. Stop after 5 packets or 30 minutes; repeat measurements count toward that limit. Propose the complete contract for approval before setup or execution. ``` Note the instruction to measure two baselines, and to repeat each candidate before a keep. A single measurement of a noisy benchmark is not evidence, and the contract asks for the repetition up front. The stop condition counts repeated measurements toward the limit too, so you cannot buy extra attempts by measuring more often. There is also a path for when you do not know what the benchmark should be. You describe the outcome you want and ask Codex to propose one, and the README states that Codex can inspect a few relevant project files to propose commands and paths, citing where each came from. Those proposals stay unaccepted until you review the complete contract. ## setup, state, next, log, finalize-preview Once the contract is accepted, the loop is short, and the README gives the sequence directly. ```bash setup -> accept contract -> state -> next -> log -> state -> finalize-preview ``` Each step has one job. The state step compiles the current files and the Git state into one decision. The next step may run only the evaluator and the checks that the accepted contract allows, which is how the scope restriction is enforced at execution time rather than by trust. The log step records whether the result was a baseline, a keep, a discard or a failure, and returns the resulting decision. The finalize-preview step supplies the currently accepted changes, the exclusions and the blockers as a compact evidence receipt. There is also a fit step in front of the loop, which decides which of three routes to take. ```bash fit -> continue directly | ask for contract input | run accepted loop ``` In direct mode, Codex states the outcome and its uncertainty, gathers the cheapest useful evidence, does the task, verifies it and bounds the claim. Importantly, in that path Autoresearch creates no session files or other state, and an unrelated existing session is left untouched. One handoff detail is worth noting. A single coherent change can be handed off on the existing branch, and separating mixed experiment history into new branches is described as an advanced step. In other words, the default is to work on your branch, with branch hygiene as something you opt into. ## One printed line decides everything The contract between the benchmark and the loop is a single line of output. ```bash METRIC seconds=12.34 ``` The primary metric decides whether the result moved in the right direction, and the direction is part of the contract, since the example declares that lower is better for seconds. Checks protect correctness, so a fast change that breaks a test is a failure rather than a keep. There is room for more than one number. Secondary metrics exist to catch known tradeoffs, and the README gives the example of lower runtime arriving with much higher memory use. That is the mechanism that stops the loop from optimising the one number you named while quietly regressing something else. If you care about memory alongside speed, the contract has to name it. The session record lives in the target project rather than in a central location. In a Git repository, temporary packet state goes under .git/autoresearch/, and outside Git it falls back to local worktree files. The state, doctor, recommendations, finalization and the dashboard all read the same snapshot and decision, and they retry if the sources change during a read, which is what keeps a concurrent edit from producing a stale verdict. The dashboard reads from that same snapshot, so the numbers you see are the numbers the loop acted on. ## What the plugin may do to your Git state This is the part to read twice, because it is the part that touches your working tree. Some commands can change Git state. Keeping a result can create a commit limited to the configured paths. Discards, crashes and failed checks can clean up the configured or explicitly supplied experiment paths. A plain measurement never stages, commits or reverts anything. Finalization begins with a read-only preview, and review branches are created only after approval. So the blast radius is bounded by the scope you configured, and it is asymmetric: measurement is inert, while keep and discard are the two paths that can write. The cleanup behaviour on a crash is the one that surprises people, since an aborted run may still remove paths under the experiment paths. The README points to a trust document for the details, and the repository root carries a SECURITY.md and a CODE_OF_CONDUCT.md alongside an AGENTS.md and a CONTRIBUTING.md. The repository itself is small in structure. The top level holds documentation and governance files, plus a plugins directory, and the plugin source lives under plugins/codex-autoresearch with its own docs and assets. The licence is Apache-2.0, with the LICENSE file at the root. ## The honest caveat in the 3.0 release notes Read the 3.0 paragraph carefully, because it sets the expectations the project wants. The release is based on engineering verification. No model driven comparison has been run, so it makes no claim of better outcomes or lower cost than ordinary Codex or than version 2.9.0. The comparison protocol and collection harness is described as optional and stays disabled unless a study receives a separate budget. That is unusual to find in a release announcement for an agent tool, and it is the most useful sentence in the README for a prospective adopter. It tells you that the loop machinery, the contract, the trust boundaries and the evaluation harness have been checked as engineering, and it tells you that nobody has yet measured whether running this loop produces better code than asking Codex directly. The same honesty applies to the fit step. The README does not claim the plugin will find a better algorithm than you would, and the "help me design a trustworthy benchmark" path is explicitly framed as a direct review first, with no session created until you approve a complete repeated experiment contract. The release history shows v2.8.0 on 2026-08-29, v2.9.0 on 2026-09-05 and v3.0.0 on 2026-09-06, and the last push to the repository was on 2026-10-11. The repository is not archived. The CHANGELOG.md file at the root is where per release detail belongs. ## Conclusion Codex Autoresearch fits a repository with a repeatable, printable benchmark and a narrow set of files you are willing to let an agent edit, especially when several small attempts would teach you more than one rewrite. It does not fit taste driven work, documentation, architecture review, or any one-off fix, and the README is explicit that those stay ordinary Codex work. Before adopting, decide whether you can name a metric that prints in the METRIC key=value form the evaluator expects, agree on what counts as a keep and a discard, and read the trust document, since keeping a result can create a Git commit limited to configured paths while discards and failed checks can clean up those same paths. ## FAQ ### How do I install the codex-autoresearch plugin? Open the plugin picker in Codex with /plugins, then choose TheGreenCedar -> codex-autoresearch -> Install plugin, and start a new Codex task in the repository you want to improve. If your Codex build supports terminal marketplace management, you can register the source marketplace first with codex plugin marketplace add TheGreenCedar/AgentPluginMarketplace --ref main. ### What does Codex Autoresearch need from me before it starts? An experiment contract with a goal, a benchmark, a metric with typed semantics, correctness checks, the scope it may edit, keep and stop rules, and a budget. The contract is proposed and reviewed first, and the baseline is measured only after you accept it. ### What format must my benchmark output? It must print at least one line in the form METRIC seconds=12.34. The primary metric decides whether the result improved, and you can add secondary metrics to catch tradeoffs such as lower runtime with much higher memory use. ### Can Codex Autoresearch commit or revert my code? Keeping a result can create a commit limited to the configured paths, and discards, crashes and failed checks can clean up the configured or explicitly supplied experiment paths. A plain measurement never stages, commits or reverts anything, and finalization starts with a read-only preview. ### Is codex-autoresearch proven to beat plain Codex? No. The README states that the 3.0 release is based on engineering verification, that no model driven comparison has been run, and that it makes no claim of better outcomes or lower cost than ordinary Codex or version 2.9.0. The comparison protocol and collection harness stays disabled unless a study gets a separate budget. ### What is codex-autoresearch not meant for? The README says reviews, documentation, product research and one-off fixes normally stay ordinary Codex work, and that architecture reviews, UX, open-ended research, taste and one-shot fixes take the direct path where no session files are created. ## Sources - [Issues](https://github.com/TheGreenCedar/codex-autoresearch/issues) - [License: Apache-2.0](https://github.com/TheGreenCedar/codex-autoresearch/blob/main/LICENSE) - [README](https://github.com/TheGreenCedar/codex-autoresearch/blob/main/README.md) - [Releases](https://github.com/TheGreenCedar/codex-autoresearch/releases) - [TheGreenCedar/codex-autoresearch on GitHub](https://github.com/TheGreenCedar/codex-autoresearch) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/thegreencedar-codex-autoresearch