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.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/thegreencedar--codex-autoresearch)HTML
<a href="/listings/thegreencedar--codex-autoresearch"><img src="/api/listings/thegreencedar--codex-autoresearch/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Open the plugin picker in Codex:
/plugins
Choose `TheGreenCedar -> codex-autoresearch -> Install plugin`, then start a new Codex task in the repository you want to improve.
If your Codex build supports marketplace management from the terminal, you can register the source marketplace first:
codex plugin marketplace add TheGreenCedar/AgentPluginMarketplace --ref main
The marketplace lives in `TheGreenCedar/AgentPluginMarketplace`; this repository is the plugin source.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 147 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- # Codex Autoresearch
- ### Improve code through repeatable experiments.
- **[Install](#install)** - **[Try it](#try-it)** - **[How it works](#how-it-works)** - **[Dashboard](#dashboard)** - **[Docs](#docs)**
- </div>
- Codex Autoresearch helps improve local code against a repeatable benchmark. Give it a workload, correctness checks, an edit boundary, and a time budget. It records the baseline, evaluates small changes, and leaves a reviewable patch with the evidence behind it.
- Use it for bounded performance or resource-use experiments: faster tests, lower build time, less memory, or higher throughput on a defined workload. Reviews, documentation, product research, and one-off fixes normally stay ordinary Codex work.
- Version 3.0 also supports 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. Preparation, failed attempts, repairs, confirmation, and delivery all use that same allowance. Goals without a numeric metric can use explicit conditions and counterexamples. See [Bounded investigations](plugins/codex-autoresearch/docs/investigations.md), or use the short benchmark path below.
- The 3.0 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 2.9.0. The optional [comparison protocol and collection harness](plugins/codex-autoresearch/docs/comparative-evaluation.md) stays disabled unless a study receives a separate budget.
- 
- The screenshot uses synthetic example data.
- The loop is inspired by [karpathy/autoresearch](https://github.com/karpathy/autoresearch) and [pi-autoresearch](https://github.com/davebcn87/pi-autoresearch). This version is built around Codex, local repositories, and ordinary reviewable Git work.
- ## Install
- Open the plugin picker in Codex:
- ```text
- /plugins
- ```
- Choose `TheGreenCedar -> codex-autoresearch -> Install plugin`, then start a new Codex task in the repository you want to improve.
- If your Codex build supports marketplace management from the terminal, you can register the source marketplace first:
- ```bash
- codex plugin marketplace add TheGreenCedar/AgentPluginMarketplace --ref main
- ```
- The marketplace lives in `TheGreenCedar/AgentPluginMarketplace`; this repository is the plugin source.
- ## Try it
- After installing the plugin, open Codex in the repository you want to improve and give it a goal, a benchmark, and a boundary. Use this as a starting point for the contract:
- ```text
- /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.
- ```
- Codex first presents the workload, checks, scope, and budget for review. After you accept the contract, Autoresearch measures the baseline before any candidate change. Commands and paths in the example must match your project.
- If you do not know what the benchmark should be, say what outcome you want and ask Codex to propose one:
- ```text
- /goal @Codex Autoresearch help me design a trustworthy benchmark for my indexer's speed and memory use.
- Do this as a direct review first. Do not create a session until I approve a complete repeated experiment contract.
- ```
- Codex can inspect a few relevant project files to propose commands and paths, citing where each came from. Those proposals are unaccepted until you review the complete contract. Missing goals, metric meaning, budgets, and product tradeoffs remain decisions to make before a run.
- ## How it works
- The normal route starts with fit:
- ```text
- fit -> continue directly | ask for contract input | run accepted loop
- ```
- Architecture reviews, documentation, UX, product study, open-ended research, taste, and one-shot fixes normally continue directly. In direct mode Codex states the outcome and uncertainty, gathers the cheapest useful evidence, does the task, verifies it, and bounds the claim. Autoresearch creates no session files or other state in that path, and an unrelated existing session remains untouched.
- When repeated measurement does fit, the loop is short:
- ```text
- setup -> accept contract -> state -> next -> log -> state -> finalize-preview
- ```
- Setup prepares an experiment contract for explicit acceptance: goal, repository and checkout, typed metric semantics, evaluator, independent checks, scope, noise, keep and stop rules, and budgets. `state` compiles the current files and Git state into one decision. `next` may run only the evaluator and checks accepted by that contract. `log` records whether the result was a baseline, a keep, a discard, or a failure, then returns the resulting decision. When there is useful work to review, `finalize-preview` supplies the current accepted changes, exclusions, and blockers for a compact evidence receipt. A single coherent change can be handed off on the existing branch; separating mixed experiment history into new branches is an advanced step.
- The benchmark must print at least one line in this form:
- ```text
- METRIC seconds=12.34
- ```
- The primary metric decides whether the result moved in the right direction. Checks protect correctness. Secondary metrics can catch known tradeoffs such as lower runtime with much higher memory use.
- Autoresearch stores the session record in the target project. In a Git repository, temporary packet state lives under `.git/autoresearch/`; outside Git it falls back to local worktree files. State, doctor, recommendations, finalization, and the dashboard all use the same snapshot and decision. They retry if the sources change during a read.
- Some commands can change Git state. Keeping a result can create a commit limited to 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. The details are in [Trust](plugins/codex-autoresearch/docs/trust.md).
- ## When it helps
- Autoresearch is a good fit when you can measure the outcome repeatedly, keep the benchmark reasonably stable, protect correctness with checks, and name the part of the repository Codex is allowed to change. It is especially useful when several small attempts are more likely to teach you something than one large rewrite.
- It is probably the wrong tool for a one-off edit, a result that is mostly a matter of taste, or a benchmark so slow and noisy that another measurement adds little information.
- ## Dashboard
- The optional dashboard shows what improved, what passed, what is blocked, and the next action. Audit details are available when you need to trace a result. It is read-only; commands still run through Codex and the CLI.
- Ask Codex to serve it for a live readout or export a snapshot for review.
- ## Safety and privacy
- Autoresearch does not have a hosted backend of its own, but it runs inside a Codex session. The Codex service or model provider is a separate data path governed by its own settings and terms. Commands you approve run with your local permissions: a benchmark can read files, start processes, use credentials available through explicit packet variables or operating-system stores, contact external services, and cost money if those services charge for use. Packet processes receive a minimal environment by default; inheriting the caller's full environment requires `--packet-env-mode inherit`.
- Keep secrets out of command lines, output, experiment notes, and artifacts. Redaction is best-effort, not a security boundary. Treat ledgers and dashboard exports as project records that may contain paths, command names, output excerpts, and notes about what Codex tried.
- Read [Trust](plugins/codex-autoresearch/docs/trust.md), [Privacy](plugins/codex-autoresearch/docs/privacy.md), and [Terms](plugins/codex-autoresearch/docs/terms.md) before using the plugin on sensitive repositories or expensive workloads.
- ## Docs
- - [Start](plugins/codex-autoresearch/docs/start.md) gets the first baseline measured and logged.
- - [Walkthrough](plugins/codex-autoresearch/docs/walkthrough.md) follows one session from prompt to finalization preview.
- - [Operate](plugins/codex-autoresearch/docs/operate.md) covers running, resuming, and repairing a session.
- - [Finish](plugins/codex-autoresearch/docs/finish.md) explains the patch and evidence handoff, with branch reconstruction when needed.
- - [Troubleshooting](plugins/codex-autoresearch/docs/troubleshooting.md) starts from the symptom when something goes wrong.
- The [Docs index](plugins/codex-autoresearch/docs/index.md) has the rest, including [workflow diagrams](plugins/codex-autoresearch/docs/workflows.md) and the [architecture](plugins/codex-autoresearch/docs/architecture.md).
- ## Update or uninstall
- Use `/plugins` to refresh or uninstall the workspace plugin. Where terminal marketplace management is available, these commands manage the source registration:
- ```bash
- codex plugin marketplace add TheGreenCedar/AgentPluginMarketplace --ref main
- codex plugin marketplace upgrade TheGreenCedar
- codex plugin marketplace remove TheGreenCedar
- ```
- Removing a marketplace registration may not uninstall a plugin that is already installed in a workspace. Use the plugin UI for that.
- ## Development
- Source development requires Node.js 24 or newer, npm, and Git. See [Contributing](CONTRIBUTING.md) for local setup and verification. Packaging and release work is covered in [Maintainers](plugins/codex-autoresearch/docs/maintainers.md), and user-facing changes are recorded in [CHANGELOG.md](CHANGELOG.md).
- ## License
- [Apache License 2.0](./LICENSE). Copyright (c) 2026 Albert Najjar.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.