Development
Plugin
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.
Plugin Signal67/100Solid
maintained96
capable14
documented100
adopted62
Install
$ npx -y skills add TheGreenCedar/codex-autoresearch --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
831
Stars
60
Forks
Active
Maintenance
TypeScript
Language
Apache-2.0
License
8d ago
Last commit
3mo ago
Created
Repo: TheGreenCedar/codex-autoresearch
What's inside
README
1Codex Autoresearch
Give Codex a benchmark, a boundary, and a memory.
Install - Try it - How it works - Dashboard - Docs
Most improvement requests start out vague: make this faster, make it smaller, stop it from breaking. Codex can usually produce a plausible change. The harder part is knowing whether the change helped, whether it traded away something important, and whether the next session can pick up the work without guessing what happened.
Codex Autoresearch gives that work a memory and a measuring stick. It runs small experiments against a benchmark, records what happened, and keeps the useful results separate from the dead ends. You can stop after one baseline or let the loop run through several ideas, but either way you get an evidence trail instead of a confident paragraph about how much better everything is now.
The loop is inspired by karpathy/autoresearch and pi-autoresearch. This version is built around Codex, local repositories, and ordinary reviewable Git work.
Install
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.
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. This prompt contains the information Codex needs:
/goal @Codex Autoresearch make the unit tests faster.
Benchmark: npm test -- --runInBand
Wrap that raw command so the benchmark prints METRIC seconds=<number>.
Metric: seconds, lower is better
Checks: npm test
Scope: test runner config and test helpers only
Stop after 5 attempts or 30 minutes.
Autoresearch will measure the current result before Codex changes anything. That baseline matters. Without it, a faster-looking implementation is still just a faster-looking implementation.
If you do not know what the benchmark should be, say what outcome you want and ask Codex to propose one:
/goal @Codex Autoresearch improve the speed of my indexer's pipeline without using more memory.
Measure a baseline first. Propose a benchmark and a safe edit scope, then ask me about anything the repository cannot answer.
Codex can help build the measurement, but it cannot decide whether the measurement represents your product. That judgment stays with you.
How it works
The normal loop is short:
setup -> doctor -> next -> log -> state -> finalize-preview
Setup records the goal, metric, benchmark, checks, budget, and file scope. Doctor makes sure the benchmark can be trusted before the first experiment. next runs one benchmark packet. log records whether the result was a baseline, a keep, a discard, or a failure. state reads the ledger and tells Codex what makes sense next. When there is useful work to review, finalize-preview shows what can be turned into review branches without changing branches yet.
The benchmark must print at least one line in this form:
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 durable session record in the target project. In a Git repository, transient packet state lives under .git/autoresearch/; outside Git it falls back to local worktree files.
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.
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.
Docs, UX, architecture, and product research can use a quality-gap loop instead of a performance metric. In that mode, source-backed findings become an accepted checklist and the loop measures how many of those gaps remain. Reaching quality_gap=0 closes that checklist; it does not prove there is nothing left to discover.
Dashboard
The dashboard is optional. It gives you a live view of the metric history, the current blocker, the next action, the runtime that produced the evidence, and the state of finalization.
It is deliberately read-only. The CLI still owns setup, experiments, logging, export, and finalization. If the browser and terminal ever disagree, stop and fix the disagreement rather than choosing the answer you prefer.
Ask Codex to serve the dashboard when a visual readout would help. Use an export when you need a portable snapshot rather than live state.
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, Privacy, and Terms before using the plugin on sensitive repositories or expensive workloads.
Docs
- Start gets the first baseline measured and logged.
- Walkthrough follows one session from prompt to finalization preview.
- Operate covers running, resuming, and repairing a session.
- Finish explains how kept work becomes review branches.
- Troubleshooting starts from the symptom when something goes wrong.
The Docs index has the rest, including workflow diagrams and the architecture.
Update or uninstall
Use /plugins to refresh or uninstall the workspace plugin. Where terminal marketplace management is available, these commands manage the source registration:
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 for local setup and verification. Packaging and release work is covered in Maintainers, and user-facing changes are recorded in CHANGELOG.md.
License
Apache License 2.0. Copyright (c) 2026 Albert Najjar.
File tree
336TheGreenCedar/codex-autoresearchView on GitHub
.editorconfig
.gitattributes
.github/
ISSUE_TEMPLATE/
autoresearch_problem.yml
config.yml
feature_request.yml
pull_request_template.md
scripts/
check-workflow-policy.mjs
workflows/
auto-release.yml
ci.yml
codeql.yml
main-branch-source-guard.yml
release.yml
.gitignore
AGENTS.md
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
plugins/
codex-autoresearch/
.codex-plugin/
plugin.json
.gitignore
assets/
autoresearch.checks.ps1.template
autoresearch.checks.sh.template
autoresearch.md.template
autoresearch.ps1.template
autoresearch.sh.template
icon.svg
logo.svg
showcase/
dashboard-demo.png
showcase.md
template.html
dashboard/
index.html
src/
bootstrap.ts
components/
ContextPanels.tsx
DecisionRail.tsx
Header.tsx
laneStatus.ts
Ledger.tsx
MissionControl.tsx
ScoreStrip.tsx
SideRail.tsx
SignalStrip.tsx
trend/
ExperimentModal.tsx
focus.ts
MetricDetails.tsx
shared.ts
TrendChartFigure.tsx
TrendPanel.tsx
constants.ts
Dashboard.tsx
demoData.ts
globals.d.ts
hooks/
useCopyText.ts
useDashboardSession.ts
useDashboardTheme.ts
useLiveDashboard.ts
useRunToast.ts
useUrlState.ts
main.tsx
model/
model.ts
asi.ts
chart.ts
entries.ts
fallbacks.ts
formatting.ts
metric-definition.ts
metrics.ts
mode.ts
readout.ts
records.ts
status.ts
timeline-sampling.ts
styles.css
types.ts
docs/
architecture.md
concepts.md
control-plane.md
finish.md
hooks.md
index.md
maintainers.md
operate.md
privacy.md
recipes.md
start.md
STYLE.md
terms.md
troubleshooting.md
trust.md
walkthrough.md
workflows.md
examples/
demo-session/
autoresearch.checks.ps1
autoresearch.config.json
autoresearch.ideas.md
autoresearch.jsonl
autoresearch.md
autoresearch.ps1
autoresearch.sh
demo.md
index.md
lib/
action-metadata.ts
active-progress-store.ts
active-progress-writer.ts
approval-ledger.ts
benchmark/
budget-contract.ts
command-input.ts
contract-guards.ts
contract-snapshot.ts
multi-metric-constraints.ts
check-policy.ts
checked-write.ts
checks/
check-common.ts
demo-trust.ts
npm-command.ts
package-checksum.ts
package-smoke.ts
product-phase.ts
source-checkout-launcher.ts
source-hygiene.ts
cli/
cli-handlers.ts
args.ts
help.ts
options.ts
source-hygiene.ts
workdir-context.ts
command-execution-boundary.ts
command-rendering.ts
command-table.ts
commands/
continuation.ts
dashboard.ts
doctor.ts
inspect.ts
lane-runner.ts
log.ts
partial-results.ts
recommend-next.ts
run.ts
session-forensics.ts
state.ts
context-capsule.ts
dashboard-command-safety.ts
dashboard-health.ts
dashboard-ledger-bounds.ts
dashboard-ledger.ts
dashboard-server-registry.ts
dashboard-transport.ts
dashboard-view-model/
dashboard-view-model.ts
ai-summary.ts
mission-control.ts
decision-authority.ts
decision-guidance.ts
decision-thresholds.ts
drift-doctor.ts
evidence-index.ts
evidence-maturity.ts
evidence-redaction.ts
evidence-registry.ts
experiment-economics.ts
experiment-memory.ts
finalization-acceptance.ts
finalization-plan.ts
finalization-runway.ts
finalize-preview.ts
fixed-control.ts
gate-quality.ts
git-paths.ts
git-private-state.ts
git-ref.ts
goal-frame.ts
lane-briefs.ts
lane-lifecycle.ts
lane-orchestration-controller.ts
last-run-store.ts
ledger-health.ts
literal-paths.ts
live-server.ts
loop-governance.ts
operator-checklist.ts
operator-readout.ts
operator-snapshot.ts
operator-warnings.ts
packet-diagnostics.ts
parallel-orchestration.ts
partial-results.ts
path-containment.ts
plugin-version.ts
portfolio-advisor.ts
preflight-audit.ts
process-governor.ts
product-claim-coverage.ts
recipes.ts
required-cleanup.ts
research-gaps.ts
research-path-guard.ts
run-status.ts
runner-progress.ts
runner.ts
runtime-drift-doctor.ts
runtime-paths.ts
safe-command-resolver.ts
session-artifacts.ts
session-core.ts
session-decision-capsule.ts
session-forensics.ts
session-mutation-lock.ts
session-paths.ts
session-read-model.ts
session-records.ts
source-cleanliness.ts
state-finalization-readout.ts
task-artifact-indexer.ts
terminal-report.ts
tool-contracts.ts
tool-registry.ts
tool-schemas.ts
tool-unsafe-command-gate.ts
truth-signals.ts
types/
dashboard-wire.ts
json.ts
packet.ts
session.ts
watchdog-summary.ts
workflow-friction.ts
LICENSE
package-lock.json
package.json
scripts/
autoresearch.mjs
autoresearch.ts
bootstrap-runtime.mjs
check-runner.ts
check.mjs
check.ts
command-surface-map.ts
directory-swap.mjs
finalize-autoresearch.mjs
finalize-autoresearch.ts
normalize-dashboard-build.mjs
operator-task-benchmark.mjs
operator-task-benchmark.ts
release-integrity.mjs
skills/
codex-autoresearch/
agents/
openai.yaml
references/
dashboard-trust.md
loop-operations.md
research-finalize.md
SKILL.md
tests/
benchmark-constraints.test.ts
bootstrap-runtime.test.ts
check-runner.test.ts
cli/
artifact-contracts.test.ts
benchmark-segments.test.ts
clear-setup-plan.test.ts
dashboard-doctor.test.ts
dashboard-health-state.test.ts
decision-log-state.test.ts
entrypoint-startup.test.ts
export-streams.test.ts
git-transactions.test.ts
guidance-finalization.test.ts
help.test.ts
lane-orchestration.integration.test.ts
lane-runner.test.ts
ledger-state.test.ts
packet-lifecycle.test.ts
research-setup.test.ts
runtime-release.test.ts
session-forensics.test.ts
setup-config-tools.test.ts
command-builders.test.ts
dashboard/
dashboard-browser-a11y.test.mjs
dashboard-browser-fixture.mjs
dashboard-cross-browser.test.mjs
dashboard-server-registry.test.ts
accessibility-layout.test.ts
action-rail.test.ts
bootstrap-payload.test.ts
chart-metrics.test.ts
command-safety-export.test.ts
decision-governance.test.ts
ledger-bounds.test.ts
ledger-evidence.test.ts
live-server-readout.test.ts
research-trust.test.ts
test-helpers.ts
decision-guidance-dashboard-health.test.ts
decision-guidance-gate-quality.test.ts
decision-guidance-lane-briefs.test.ts
decision-guidance-runtime-drift.test.ts
decision-guidance-task-artifacts.test.ts
decision-guidance-terminal-report.test.ts
evidence-core.test.ts
experiment-memory.test.ts
finalize/
cleanup-safety.test.ts
cli-and-artifacts.test.ts
collapse.test.ts
current-tree.test.ts
evidence-gates.test.ts
git-ref.test.ts
helpers.ts
history-integrity.test.ts
plan-contracts.test.ts
progress.test.ts
review-branches.test.ts
fixtures/
stubborn-process-tree.mjs
helpers/
cli-session.ts
cli-test-context.ts
dashboard-export.ts
dashboard.ts
git-fixtures.ts
ledger.ts
process-fixtures.ts
process.ts
runtime-release-fixtures.ts
server.ts
session-forensics-fixtures.ts
hostile-workflow.test.ts
loop-governance.test.ts
operator-task-benchmark.test.ts
packet-diagnostics.test.ts
process/
runner-process-lifecycle.test.ts
product/
product-claim-coverage.test.ts
contract-integrity.test.ts
core-and-runner.test.ts
decision-truth.test.ts
helpers.ts
release-and-live.test.ts
research-workflows.test.ts
setup-and-recipes.test.ts
session-control-plane.test.ts
source-hygiene.test.ts
state-finalization-readout.test.ts
tsconfig.dashboard.json
tsconfig.json
tsconfig.node.json
tsdown.config.ts
vite.dashboard.config.ts
README.md
SECURITY.mdFAQ
codex-autoresearch is a Claude Code plugin with 1 hand-picked skill for development work, indexed on Flowy. Install it with the command on its page. It includes codex-autoresearch. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is 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.
- How do I install codex-autoresearch?
- Run these in Claude Code: npx -y skills add TheGreenCedar/codex-autoresearch --agent claude-code. Then prompt normally.
- Does codex-autoresearch auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is codex-autoresearch free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.