Codex Autoresearch

codex-autoresearch

Autonomous goal-directed iteration. Modify -> Verify -> Keep/Discard -> Repeat.

When Activated

1. Classify the request as loop, plan, debug, fix, security, ship, or exec, and parse any inline config from the prompt. 2. Load references/core-principles.md and references/structured-output-spec.md. For active execution modes (loop, debug, fix, security, ship, exec), also load references/runtime-hard-invariants.md. 3. Load only the additional references the current situation needs:

• references/session-resume-protocol.md for every interactive launch or existing-run control path, before deciding fresh vs resumable
• references/environment-awareness.md before choosing hardware-sensitive work
• references/interaction-wizard.md for every new interactive launch (loop, debug, fix, security, ship) before execution begins
• references/results-logging.md only when debugging TSV/state semantics or helper behavior directly

4. Load the selected mode workflow reference plus only the detailed cross-cutting protocols that actually apply (lessons, pivot, health-check, parallel, web-search, hypothesis-perspectives). 5. Use the bundled helper scripts when stateful artifacts or runtime control are involved. Resolve them relative to the loaded skill bundle root (<skill-root>/scripts/...), not the target repo root. In the common repo-local install this means commands such as python3 .agents/skills/codex-autoresearch/scripts/autoresearch_init_run.py --repo <primary_repo> --workspace-root <workspace_root> .... New-run helpers (autoresearch_init_run.py and autoresearch_runtime_ctl.py launch/create-launch) require both --repo <primary_repo> and --workspace-root <workspace_root>. Existing-run control-plane helpers (autoresearch_resume_check.py, autoresearch_resume_prompt.py, autoresearch_supervisor_status.py, autoresearch_health_check.py, autoresearch_runtime_ctl.py status/stop/start) require --repo <primary_repo> and resolve the workspace-owned Results directory from the repo-local pointer plus canonical context. autoresearch_launch_gate.py --repo <primary_repo> is the pre-wizard gate: it returns fresh for a clean repo with no prior artifacts and otherwise uses the same pointer/context recovery path. 6. Execute the selected workflow exactly as written and produce the required structured output and artifacts.

Core Loop

1. Read the relevant context. 2. Define a mechanical success metric. 3. Establish a baseline. 4. Make one focused change. 5. Verify with a command. 6. Keep or discard the change. 7. Log the result. 8. Repeat.

Modes

Use Mode: <name> in the prompt to force a specific subworkflow.

Required Config

For the generic loop, the following fields are needed internally. Codex infers them from the user's natural language input and repo context, then fills gaps through guided conversation:

• Goal
• Scope
• Metric
• Direction
• Verify

Optional but recommended:

• Guard
• Iterations
• Run tag
• Stop condition

For every new interactive run, use the wizard contract in references/interaction-wizard.md.

Explicit Run Modes

• Use $codex-autoresearch for interactive autoresearch launches and follow-up controls.
• For a new interactive run, scan the repo, ask the confirmation questions, and require an explicit run-mode choice: foreground or background.
• If the user chooses foreground, keep the loop in the current Codex session. When model-visible goal tools are available, use the official Codex goal only as the thread-level continuation anchor: after launch approval, call get_goal; reuse a matching non-complete current goal, or call create_goal with the confirmed objective when no goal exists. If an existing goal cannot be reused, surface it in the confirmation summary before launch and do not create a second one. Mark the goal complete with update_goal only when the autoresearch stop condition is actually satisfied; mark it blocked only when the run truly cannot continue without external input or an environment change. Use the shared helper scripts (autoresearch_init_run.py --repo <primary_repo> --workspace-root <workspace_root>, autoresearch_record_iteration.py, autoresearch_select_parallel_batch.py, autoresearch_supervisor_status.py --repo <primary_repo>) and do not create launch/runtime control artifacts.
• If the user chooses background, call autoresearch_runtime_ctl.py launch --repo <primary_repo> --workspace-root <workspace_root> to persist the confirmed launch manifest and start the detached runtime controller in one step, then return a short handoff summary instead of tailing or polling the run unless the user explicitly asked you to wait. Do not create or mutate official Codex goals for background runs; the runtime controller owns detached continuation. The runtime itself should execute non-interactive codex exec sessions with the generated runtime prompt supplied on stdin. Detached sessions default to danger_full_access (--dangerously-bypass-approvals-and-sandbox) unless the user explicitly asks for the sandboxed workspace_write path. If the mini-wizard outcome is "fresh start", call autoresearch_runtime_ctl.py launch --repo <primary_repo> --workspace-root <workspace_root> --fresh-start so prior persistent run-control artifacts are archived as part of the same handoff.
• If the user resumes an existing interactive run in the other mode, synchronize autoresearch-results/state.json internally before continuing. Background start already performs that sync automatically before it relaunches nested Codex sessions; autoresearch_set_session_mode.py remains an internal/scripted recovery helper, not a normal user-facing step.
• Treat the repo where the run starts as the primary repo. Single-repo runs are the default. If the task truly spans multiple codebases, declare companion repos explicitly and give each repo its own scope instead of stuffing absolute paths into one mixed scope string.
• For a new interactive run, default the workspace_root from the launch context: if Codex started inside a git repo, use that repo root; otherwise use the current launch directory. Do not silently widen to a parent workspace just because sibling repos or old artifacts exist. Only widen when the user explicitly confirms a broader multi-repo workspace, and show the resulting Results directory in the confirmation summary.
• Foreground and background share the same experiment protocol, but they are mutually exclusive for a given workspace/run. Never try to keep both modes active against the same autoresearch-results/ artifacts at the same time.
• For every interactive foreground/background launch that proceeds past the session-resume gate, check python3 <skill-root>/scripts/autoresearch_hooks_ctl.py status and then follow the readiness flow in references/interaction-wizard.md. Capture the first startup_tip_needed value from that status; if it is true, include one product-facing launch tip in the confirmation summary. If setup is missing, stale, disabled, or untrusted, run python3 <skill-root>/scripts/autoresearch_hooks_ctl.py install before clarification continues. Treat setup details as internal preparation unless a setup failure blocks launch. Use model-visible goal tools when they are actually available.
• For status, stop, or resume requests, stay on the same skill entry. status and stop apply to background runs only; foreground runs stay in the current session.
• exec remains the advanced / CI path. It is fully specified upfront and does not use the interactive handoff.

Hard Rules

1. Ask before act for new interactive launches. For loop, debug, fix, security, and ship, scan the repo, run the session-resume launch gate, and ask at least one repo-grounded confirmation round before the run starts. Load and follow references/interaction-wizard.md for every new interactive launch. The launch wizard must include an explicit run-mode choice: foreground or background. exec mode is the exception: it is fully configured upfront and must not stop for a launch question. 2. Respect the chosen run mode after launch approval. In interactive modes, once the user says "go" (or equivalent: "start", "launch", or any clear approval), follow the selected run mode exactly. Foreground stays in the current session, may align the official Codex goal when goal tools are available, and must not call autoresearch_runtime_ctl.py launch. Background calls autoresearch_runtime_ctl.py launch --repo <primary_repo> --workspace-root <workspace_root>, creating the confirmed launch manifest and detached runtime as a single script-level action; after launch, return a short handoff summary and do not monitor in the foreground unless explicitly asked. Background must not create or update official Codex goals. Detached sessions use the confirmed launch manifest's execution_policy and default to danger_full_access unless the user explicitly asks for sandboxed workspace_write. If the chosen background path is a fresh start after recovery analysis, use autoresearch_runtime_ctl.py launch --repo <primary_repo> --workspace-root <workspace_root> --fresh-start so stale persistent run-control artifacts are archived automatically. exec mode has no launch question; once safety checks pass, it begins immediately. 3. Never ask after the user approves the run. Once the user has approved go in either foreground or background mode, do not pause mid-run to ask anything -- not for clarification, not for confirmation, not for permission. If you encounter ambiguity during the loop, apply best practices and keep going. The user may be asleep. 4. Read all in-scope files before the first write. 5. One focused change per iteration. 6. Mechanical verification only. 7. After launch approval, scoped per-iteration trial commits are part of the approved run; do not ask separately before creating them. Create a trial commit before verification only when every managed repo's worktree stays within that repo's declared scope or autoresearch-owned artifacts, remove generated verify/guard byproducts, apply the approved keep/discard closeout, then record the current clean HEAD commit(s). The background runtime enforces the same scope-aware gate before each relaunch boundary, but foreground runs must still honor it before creating a trial commit. 8. Never stage or revert unrelated user changes. 9. Keep run artifacts uncommitted and never stage them. 10. Use the rollback strategy approved during setup. In a dedicated experiment branch/worktree with pre-launch approval, git reset --hard HEAD~1 is allowed; otherwise use git revert --no-edit HEAD. 11. Discard gains under 1% that add disproportionate complexity. 12. Unlimited runs by default unless the user explicitly asks for Iterations: N. 13. External ship actions (deploy, publish, release) must be confirmed during the pre-launch wizard phase. If not confirmed before launch, skip them and log as blocker. 14. Do not ask "should I continue?". Once launched, keep the chosen run mode active until interrupted or a hard blocker / configured terminal condition appears (see references/autonomous-loop-protocol.md Stop Conditions for the full definition). 15. During active execution, keep references/runtime-hard-invariants.md as the primary runtime checklist. Foreground's core persistent artifacts are autoresearch-results/results.tsv, autoresearch-results/state.json, autoresearch-results/context.json, and autoresearch-results/lessons.md; background also uses autoresearch-results/launch.json, autoresearch-results/runtime.json, and autoresearch-results/runtime.log. 16. When stuck (3+ consecutive discards), use the PIVOT/REFINE escalation ladder from references/pivot-protocol.md instead of brute-force retrying. 17. Prefer the bundled helper scripts over hand-editing autoresearch-results/results.tsv, autoresearch-results/state.json, autoresearch-results/context.json, or runtime-control files. Always call them via the skill-bundle path (<skill-root>/scripts/...); never call bare scripts/autoresearch_*.py from the target repo root unless the skill bundle itself is actually installed there. 18. In exec mode, never leave repo-root state artifacts behind. If helper scripts need state, use the exec scratch path and explicitly clean it up before exit. New schema artifacts still belong under the workspace-owned autoresearch-results/ directory; legacy repo-root artifacts trigger the unsupported-layout error unless the user explicitly chooses a fresh start. 19. After any context compaction event (the CLI warns about thread length and compaction), re-read references/runtime-hard-invariants.md, references/core-principles.md, and the selected mode workflow from disk before the next iteration. Do not rely on memory of those documents after compaction. 20. Every 10 iterations, perform the Protocol Fingerprint Check defined in references/runtime-hard-invariants.md. Use Phase 8.7 of references/autonomous-loop-protocol.md only for the detailed re-anchoring procedure. If any item fails, re-read all loaded runtime docs from disk before continuing.

Structured Output

Every mode should follow references/structured-output-spec.md.

Minimum requirement:

• for interactive and user-facing modes, print a setup summary before the loop starts,
• for interactive and user-facing modes, print progress updates during the loop,
• for interactive and user-facing modes, print a completion summary at the end,
• for exec, emit no prose; every assistant-visible payload must be one of the JSON lines defined in references/exec-workflow.md,
• write the mode-specific output files when the workflow defines an output directory.

Quick Start

$codex-autoresearch
I want to get rid of all the `any` types in my TypeScript code

$codex-autoresearch
I want to make our API faster but I don't know where to start

$codex-autoresearch
pytest is failing, 12 tests broken after the refactor

Codex scans the repo, asks targeted questions to clarify your intent, asks you to choose foreground or background for interactive runs, then starts the loop. You never need to write key-value config.

References

• references/core-principles.md
• references/runtime-hard-invariants.md
• references/loop-workflow.md
• references/autonomous-loop-protocol.md
• references/interaction-wizard.md
• references/structured-output-spec.md
• references/modes.md
• references/plan-workflow.md
• references/debug-workflow.md
• references/fix-workflow.md
• references/security-workflow.md
• references/ship-workflow.md
• references/exec-workflow.md
• references/results-logging.md
• references/lessons-protocol.md
• references/pivot-protocol.md
• references/web-search-protocol.md
• references/environment-awareness.md
• references/parallel-experiments-protocol.md
• references/session-resume-protocol.md
• references/health-check-protocol.md
• references/hypothesis-perspectives.md

Contributing to codex-autoresearch

This project is a Markdown-first Codex skill with a small set of helper scripts and stdlib tests. There is still no build step and no runtime dependency installation. Most changes are .md edits, but stateful behavior now also lives in scripts/ and is validated by tests/.

How the skill is structured

Codex loads SKILL.md first. That file contains mode routing, hard rules, and a load order that pulls in reference files on demand:

SKILL.md  (always loaded -- entrypoint)
  |
  +-- references/core-principles.md         (always loaded)
  +-- references/structured-output-spec.md  (always loaded)
  +-- references/runtime-hard-invariants.md (always loaded for active execution)
  +-- references/session-resume-protocol.md (check for prior run)
  +-- references/environment-awareness.md   (probe hardware/toolchains)
  +-- references/loop-workflow.md           (loaded for default loop execution)
  +-- references/interaction-wizard.md       (loaded for every new interactive launch)
  +-- references/{mode}-workflow.md          (loaded per mode)
  +-- references/autonomous-loop-protocol.md (detailed loop reference)
  +-- references/results-logging.md          (loaded for TSV/state troubleshooting)
  +-- references/lessons-protocol.md         (loaded when lessons behavior matters)
  +-- references/pivot-protocol.md           (loaded when stuck recovery is active)
  +-- references/health-check-protocol.md    (loaded when integrity checks are needed)
  +-- references/hypothesis-perspectives.md  (loaded when beneficial)
  +-- references/parallel-experiments-protocol.md (loaded when parallel enabled)
  +-- references/web-search-protocol.md      (loaded when web search enabled)
  +-- references/modes.md                    (mode index)

This progressive disclosure means Codex only reads what it needs. A loop-mode invocation never loads the ship workflow. A plan-mode invocation never loads the results log spec.

The user-facing documentation lives in separate files:

README.md / docs/i18n/README_*.md    -- public overview
docs/GUIDE.md                        -- operator's manual
docs/EXAMPLES.md                     -- real-world recipes
docs/INSTALL.md                      -- installation options

Development workflow

1. Fork and clone the repo.

2. Symlink into a test project so edits take effect immediately:

ln -s /path/to/your/fork your-project/.agents/skills/codex-autoresearch

3. Open Codex in the test project, type $codex-autoresearch, and verify the skill activates.

4. Make your changes. Test by invoking the skill in different scenarios. Do not treat the stdlib tests as the whole acceptance bar for behavior changes.

5. When satisfied, remove the symlink and submit a PR.

Where to make changes

The project has two layers: the skill layer (what Codex reads) and the documentation layer (what humans read). Changes often touch both.

Skill layer -- how Codex behaves:

Documentation layer -- what humans see:

When a skill-layer change affects user-visible behavior, update the documentation layer too. When a change touches the optional user-level hooks, also update tests/autoresearch/test_hooks_ctl.py and rerun the runtime smoke coverage.

Adding a new mode

1. Create references/yourmode-workflow.md. Include: purpose, trigger phrases, phases with rules, output format, and a two-phase boundary statement at the top.

2. Add the mode to the table in SKILL.md and to the classification list in "When Activated."

3. Add it to references/modes.md and update the Shared Expectations list if needed.

4. Add field mappings to references/interaction-wizard.md so the wizard knows how to guide users into this mode.

5. Add a section to README.md, update the maintained docs/i18n/README_*.md files, update docs/GUIDE.md, and add at least one recipe to docs/EXAMPLES.md.

6. Run bash scripts/validate_skill_structure.sh to verify the file structure.

Submitting a PR

Use conventional commit format for titles:

• feat: -- new functionality (mode, feature, recipe)
• fix: -- corrects wrong behavior in skill instructions
• docs: -- documentation-only changes
• refactor: -- reorganizes content without changing behavior

In the PR body, explain what changed and how to test it. A good test is: symlink the branch into a project, invoke $codex-autoresearch with a relevant prompt, and observe whether Codex follows the updated instructions.

Keep PRs focused. One logical change per PR.

What makes a good contribution

High-value contributions:

• Recipes for domains not yet covered in docs/EXAMPLES.md
• Improvements to the interaction wizard (better questions, better defaults)
• Protocol refinements backed by real-world testing (e.g., "the PIVOT threshold should account for near-miss iterations")
• Translations of documentation to new languages
• Bug reports with reproduction steps ("I said X, Codex did Y, expected Z")

Please avoid:

• Reformatting or restyling existing files without functional changes
• Adding verbose comments or explanations for self-evident content
• Bumping version numbers (maintainers handle releases)

Contributor Gate

The automated tests are real and useful, but they do not all validate the same layer:

• tests/autoresearch/ executes the helper scripts directly and checks TSV/JSON semantics.
• tests/test_check_skill_invariants.py validates the invariant checker itself.
• bash scripts/run_skill_e2e.sh exec-smoke --clean runs the real skill through codex exec in a disposable fixture repo.
• bash scripts/run_skill_e2e.sh runtime-smoke --clean automatically exercises the detached runtime launch/status/stop handoff with an installed skill copy and a fake Codex binary.

That means python3 -m unittest ... alone is not enough to prove the skill still works end to end.

Use this gate table:

The interactive-smoke harness prints the exact manual verification steps. Keep it manual for conversational behavior that the automated gate cannot prove. The detached runtime handoff itself is now covered automatically by runtime-smoke.

Changes to the optional long-running hooks surface (autoresearch_hooks_ctl.py, autoresearch_hook_*.py, related README/GUIDE/INSTALL text) count as skill-level changes. At minimum, cover both sides of the boundary: hooks must stay inert for unrelated Codex conversations in the same repo, and they must still engage for opted-in autoresearch sessions.

Validating your changes

bash scripts/run_contributor_gate.sh docs
bash scripts/run_contributor_gate.sh skill

docs is the lightweight structure check. skill is the real automated contributor gate: structure validation, helper/invariant unit tests, and a disposable codex exec smoke run.

For real skill-level validation against Codex CLI itself:

bash scripts/run_skill_e2e.sh exec-smoke
bash scripts/run_skill_e2e.sh runtime-smoke
bash scripts/run_skill_e2e.sh interactive-smoke

exec-smoke runs the real skill through codex exec in a disposable fixture repo and checks artifact invariants. runtime-smoke automatically exercises the installed-skill detached runtime handoff. interactive-smoke prepares a disposable repo and prints the exact manual wizard/go smoke-test steps for the still-human conversational layer.

For interactive behavioral validation, there is no fully automated suite. The skill is Markdown instructions plus helper scripts -- the only way to test wizard and autonomy boundaries is to use it. Symlink your branch, invoke the skill with various prompts, and verify Codex follows the updated instructions.

Edge cases worth trying:

• Invoke with no context ("$codex-autoresearch" and nothing else) -- does the wizard activate?
• Invoke with a complete goal -- does the wizard still ask at least one confirming question?
• Let the loop run for 5+ iterations -- does it behave correctly on keep, discard, and crash?

Architecture decisions to be aware of

• Progressive disclosure is intentional. Do not move reference content into SKILL.md. The entrypoint should stay small.
• The two-phase boundary is a core design constraint. Everything before "go" can ask the user. Everything after "go" must be fully autonomous.
• Natural language is the primary interface. Users should never need to know field names or write structured config. The wizard handles translation.
• Rollback must match the pre-launch approval. In an isolated experiment branch/worktree, approved git reset --hard HEAD~1 is allowed; otherwise use git revert --no-edit HEAD.
• Lessons are additive. Cross-run learning persists across sessions. Never delete lessons without user consent.
• PIVOT/REFINE replaces brute-force retrying. Stuck recovery should always escalate through the defined ladder.

License

MIT. Contributions are made under the same license.

Recipes

Working examples organized by what you want to accomplish. Each recipe shows what you say to Codex, what Codex does, and the configuration it generates internally. You only need the one-liner -- Codex figures out the rest.

---

Table of Contents

• Iterating Toward a Target
• Fixing Broken Things
• Hunting Bugs
• Auditing for Vulnerabilities
• Planning When You Are Unsure
• Releasing with Confidence
• Chaining Modes
• CI/CD Mode (exec)
• MCP Integration
• Choosing Verify and Guard Commands

---

Iterating Toward a Target

These all use loop mode. You state a goal, Codex proposes metrics and verification, you say "go."

Eliminate any types in TypeScript

You:   $codex-autoresearch
       Get rid of all the `any` types in my TypeScript code

Codex: I found 47 `any` occurrences across src/**/*.ts.

       Confirmed:
       - Target: eliminate `any` types in src/**/*.ts
       - Metric: `any` count (current: 47), direction: lower
       - Verify: grep count + tsc --noEmit as guard

       Need to confirm:
       - Run until all gone, or cap at N iterations?

You:   Go, run overnight.

What Codex does each iteration: picks one any usage, replaces it with a proper type annotation, verifies the count dropped and tsc still compiles, keeps or reverts.

Raise Python test coverage

You:   $codex-autoresearch
       Raise my test coverage from 58% to at least 85%

Codex: Found 58% coverage across src/.

       Confirmed:
       - Target: 85%+ test coverage
       - Metric: coverage percentage, direction: higher
       - Verify: pytest coverage report
       - Guard: ruff linter

       Need to confirm:
       - Should I write new test files or only add to existing ones?
       - Any modules to prioritize?

You:   Either is fine. Start with src/auth/ and src/api/. Go.

What Codex does each iteration: identifies an uncovered function or branch, writes a test for it, verifies coverage increased and lint still passes, keeps or reverts.

Reduce API response time

You:   $codex-autoresearch
       The /search endpoint p95 is 800ms, get it under 200ms

Codex: Found the search handler in src/api/search.ts. It queries
       PostgreSQL with 3 JOINs and no index hints.

       Confirmed:
       - Target: p95 latency under 200ms for /search
       - Metric: p95 latency in ms, direction: lower
       - Verify: benchmark script, Guard: existing test suite

       Need to confirm:
       - Can I add database indexes, or code-only changes?
       - Is there a load testing script I should use?

You:   You can add indexes. Use `npm run bench:search` for benchmarks. Go.

Strategies Codex will try: adding database indexes, optimizing query structure, introducing caching, reducing middleware overhead, batching related queries.

Shrink Webpack build warnings

You:   $codex-autoresearch
       Eliminate all the Webpack build warnings

Codex: Found 23 warnings in the last build output.

       Confirmed:
       - Target: zero build warnings
       - Metric: warning count, direction: lower
       - Verify: build output warning count
       - Guard: unit test suite

       Need to confirm:
       - Should I also address deprecation notices?

You:   Yes. Go, 15 iterations max.

Speed up the CI pipeline

You:   $codex-autoresearch
       CI takes 14 minutes, I need it under 6

Codex: Analyzed .github/workflows/ci.yml. The test job runs sequentially
       and installs dependencies from scratch each time.

       Confirmed:
       - Target: CI duration under 6 minutes
       - Metric: total pipeline time, direction: lower
       - Verify: local test timing as proxy
       - Guard: all tests must still pass

       Need to confirm:
       - Can I modify the workflow YAML, or code-only?
       - Is the Docker build step required on every push?

You:   You can modify the workflow. Docker build only on main. Go.

Strategies Codex will try: parallelizing test shards, caching node_modules/pip packages, skipping redundant steps on feature branches, splitting slow integration tests into a separate job.

Optimize a noisy multi-metric scheduler

Use metrics_json when one scalar cannot describe success. This is common for schedulers, route planners, solvers, recommender systems, or any workflow where several business metrics move together and individual metrics have run-to-run noise.

You:   $codex-autoresearch
       Improve my CP-SAT course scheduler. The verify command prints JSON metrics.
       Keep hard conflicts at zero, reduce late events and room waste, and use
       the overall judge score as the primary metric.

Codex: Found `scripts/schedule_metrics.py` and sample cases under tests/cases/.

       Confirmed:
       - Target: improve schedule quality while preserving feasibility
       - Metric: overall judge score, direction: higher
       - Verify: `python3 scripts/schedule_metrics.py --json`
       - Also keeping: hard_conflicts == 0, unsatisfied_constraints == 0

       Need to confirm:
       - Should I run the full case suite or the fastest representative case?
       - Run mode: foreground or background?

You:   Use the representative case first. Background. Go.

The verify command should print a JSON object as its final non-empty line:

{
  "judge_score": 0.71,
  "hard_conflicts": 0,
  "unsatisfied_constraints": 0,
  "late_events": 74,
  "room_waste": 19470.0
}

Internally this maps to verify_format=metrics_json, primary_metric_key=judge_score, acceptance criteria such as hard_conflicts == 0, and required keep criteria for feasibility invariants. Codex should optimize the primary score but mechanically reject any retained result that violates the hard constraints.

Make clippy happy in Rust

You:   $codex-autoresearch
       Clean up all the clippy warnings in the Rust codebase

Codex: Found 31 clippy warnings across src/.

       Confirmed:
       - Target: zero clippy warnings
       - Metric: warning count, direction: lower
       - Verify: cargo clippy output
       - Guard: cargo test

       Need to confirm:
       - Should I also address `cargo clippy -- -W clippy::pedantic`?

You:   No, just the default warnings. Go.

---

Fixing Broken Things

Fix mode iterates until the error count reaches zero. It auto-detects what is broken.

Fix all pytest failures

You:   $codex-autoresearch
       pytest is failing, 12 tests broken after the refactor

Codex: I see 12 failures across tests/.

       Confirmed:
       - Target: make all pytest tests pass
       - Current: 12 failures

       Need to confirm:
       - Should I also guard with ruff to avoid introducing lint issues?
       - Fix all 12, or focus on a specific module first?

You:   Fix all, yes guard with ruff. Go.

Stops automatically when all tests pass.

Fix TypeScript compilation errors

You:   $codex-autoresearch
       tsc is throwing 28 errors after the dependency upgrade

Codex: Found 28 type errors. Most are in src/api/ -- the new version
       of express changed several type signatures.

       Confirmed:
       - Target: zero tsc errors
       - Current: 28 errors

       Need to confirm:
       - Should I also run the test suite as a guard?

You:   Yes. Go.

Fix ESLint errors after config change

You:   $codex-autoresearch
       Switched to stricter ESLint config and now there are 94 violations

Codex: Found 94 violations. Breakdown: 41 unused-vars, 23 no-explicit-any,
       18 prefer-const, 12 other.

       Confirmed:
       - Target: zero ESLint violations
       - Current: 94

       Need to confirm:
       - Should I also guard with tsc?
       - Some unused-vars might indicate dead code -- remove or suppress?

You:   Remove dead code. Guard with tsc. Go.

Fix Go vet warnings

You:   $codex-autoresearch
       Clean up all go vet issues

Codex: Found 7 go vet warnings across cmd/ and internal/.

       Confirmed:
       - Target: zero go vet warnings
       - Current: 7

You:   Go.

---

Hunting Bugs

Debug mode tests one hypothesis per iteration. Every finding needs evidence.

Intermittent 503 under load

You:   $codex-autoresearch
       API returns 503 randomly under concurrent requests

Codex: I see connection pooling in src/db/pool.ts, rate limiting in
       src/middleware/, and 3 async handlers without error boundaries.

       Confirmed:
       - Symptom: intermittent 503 under concurrent load
       - Scope: src/api/, src/db/, src/middleware/

       Need to confirm:
       - When did this start? After a specific change, or always?
       - If I find the cause, should I also fix it?

You:   Started after the connection pool refactor last week. Find cause first.

Produces a findings directory with confirmed causes, disproven hypotheses, and recommended next steps.

Search returning duplicate results

You:   $codex-autoresearch
       Paginated search results have duplicates when you go to page 2

Codex: Found the search handler in src/api/search.ts.
       It uses OFFSET/LIMIT pagination with a non-unique sort key.

       Confirmed:
       - Symptom: duplicate results on page 2+
       - Scope: src/api/search.ts, src/db/queries/

       Need to confirm:
       - Is this happening on all search endpoints or just /search?

You:   Just /search. Go.

Silent cron job failures

You:   $codex-autoresearch
       The nightly data sync job keeps failing silently, no errors in logs

Codex: Found the job in src/jobs/sync.ts. The catch block swallows
       exceptions without logging.

       Confirmed:
       - Symptom: nightly job fails with no error output
       - Scope: src/jobs/, src/services/sync/

       Need to confirm:
       - Should I also fix the error handling, or just diagnose?

You:   Diagnose first, I'll fix separately.

---

Auditing for Vulnerabilities

Security mode is read-only by default. Every finding requires file:line evidence.

API injection audit

You:   $codex-autoresearch
       Check our API layer for injection vulnerabilities

Codex: Confirmed:
       - Scope: src/api/ and src/middleware/ (14 files)
       - Focus: SQL injection, XSS, input sanitization

       Need to confirm:
       - Report only, or also fix critical findings?
       - Should I also cover auth/access control?

You:   Report first, cover auth too.

Produces a report with ranked findings, each with file:line reference and exploitation scenario.

Audit changed files only

You:   $codex-autoresearch
       Security check on just the files I changed this sprint

Codex: I see 8 modified files since the last tag. 3 are in src/api/,
       2 in src/auth/, 3 in tests/.

       Confirmed:
       - Scope: the 5 non-test modified files
       - Focus: input validation, auth changes

       Need to confirm:
       - Include the test files in scope?

You:   No, just the source files. Go.

Audit and fix in one pass

You:   $codex-autoresearch
       Find vulnerabilities and fix anything critical

Codex: [runs security audit first]
       Found 2 Critical, 3 High, 5 Medium findings.

       Switching to fix mode for 2 Critical and 3 High findings.
       ...

---

Planning When You Are Unsure

Plan mode helps you figure out what to measure and how. It never modifies code.

Not sure what metric to use

You:   $codex-autoresearch
       I want to make our API faster but I don't know where to start

Codex: I scanned the repo. API layer is in src/api/ with Express + Prisma.

       Need to confirm:
       - What matters more: p95 latency, throughput, or cold start?
       - Should I benchmark the whole API or specific endpoints?

You:   p95 latency, the /search endpoint is the worst.

Codex: Proposed configuration:
       - Goal: Reduce /search p95 latency
       - Scope: src/api/search.ts, src/db/queries/, src/middleware/
       - Metric: p95 latency (ms), direction: lower
       - Verify: npm run bench:search 2>&1 | grep p95 | awk '{print $2}'
       - Guard: npm test

       Dry-run result: verify command outputs 847 (ms).
       Ready to paste into a loop invocation.

Want to improve code quality

You:   $codex-autoresearch
       The codebase feels messy, what should I clean up first?

Codex: I scanned the repo. Here's what I found:
       - 47 `any` types in TypeScript
       - 6 files with cyclomatic complexity > 20
       - 12% of src/ has no test coverage
       - 23 Webpack build warnings

       Which of these matters most to you?

You:   Start with the `any` types.

Codex: [generates config for eliminating any types]

Want to optimize database performance

You:   $codex-autoresearch
       Help me figure out how to make our database queries faster

Codex: Found 14 query files in src/db/. The /search endpoint runs
       3 JOINs with no EXPLAIN analysis. Two queries use SELECT *.

       Need to confirm:
       - Focus on query execution time, or total endpoint latency?
       - Can I add indexes to the schema?

You:   Total endpoint latency. Yes you can add indexes.

Codex: [generates config with endpoint latency as metric]

---

Releasing with Confidence

Ship mode detects what you are releasing and generates a verification checklist.

Ship a PR

You:   $codex-autoresearch
       Ship it

Codex: Detected: PR to main with 3 commits.

       Confirmed:
       - Type: code PR
       - Target: main branch

       Need to confirm:
       - Dry run first, or go live?
       - Post-ship monitoring? (5 min / 15 min / skip)

You:   Dry run first.

Check readiness without shipping

You:   $codex-autoresearch
       Are we ready to deploy?

Codex: Running readiness checklist...
       - Tests: 142/142 passing
       - Types: clean
       - Lint: clean
       - Build: succeeds
       - No uncommitted changes
       - Branch is up to date with main

       All checks pass. Ready to ship when you are.

---

Chaining Modes

Modes compose naturally through sequential invocations.

Debug then fix

You:   $codex-autoresearch
       API returns 503 randomly under load
       [debug mode finds: pool exhaustion, missing error boundary]

You:   $codex-autoresearch
       Fix the bugs you just found
       [fix mode reads debug findings, repairs them one by one]

Plan then loop

You:   $codex-autoresearch
       I want to reduce our API latency but not sure how
       [plan mode produces config]

You:   $codex-autoresearch
       Run the plan you made
       [loop mode executes with the generated config]

Audit then fix

You:   $codex-autoresearch
       Audit the auth system, then fix anything critical
       [security mode audits, switches to fix mode for Critical/High]

---

CI/CD Mode (exec)

Non-interactive mode for automation pipelines. All config upfront, JSON output, exit codes.

Reduce type errors in GitHub Actions

- name: Reduce type errors
  run: |
    codex exec --dangerously-bypass-approvals-and-sandbox <<'PROMPT'
    $codex-autoresearch
    Mode: exec
    Goal: Reduce type errors
    Scope: src/**/*.ts
    Metric: type error count
    Direction: lower
    Verify: tsc --noEmit 2>&1 | grep -c error
    Iterations: 20
    PROMPT
  continue-on-error: true

Exit codes: 0 = improved, 1 = no improvement, 2 = hard blocker.

Raise coverage in GitLab CI

optimize-coverage:
  script:
    - |
      codex exec --dangerously-bypass-approvals-and-sandbox <<'PROMPT'
      $codex-autoresearch
      Mode: exec
      Goal: Raise test coverage
      Scope: src/
      Metric: coverage percentage
      Direction: higher
      Verify: pytest --cov=src --cov-report=term 2>&1 | grep TOTAL | awk '{print $NF}'
      Guard: ruff check .
      Iterations: 15
      PROMPT
  allow_failure: true

Nightly lint cleanup

- name: Nightly lint cleanup
  run: |
    codex exec --dangerously-bypass-approvals-and-sandbox <<'PROMPT'
    $codex-autoresearch
    Mode: exec
    Goal: Eliminate ESLint violations
    Scope: src/
    Metric: violation count
    Direction: lower
    Verify: npx eslint src/ --format compact 2>&1 | tail -1 | grep -oP '\\d+ problem'
    Guard: npm run test:unit
    Iterations: 30
    PROMPT
  schedule:
    - cron: '0 3 * * *'

---

MCP Integration

MCP (Model Context Protocol) servers extend Codex's capabilities. These recipes show how to combine autoresearch with MCP tools.

Framework docs lookup during optimization

If you have an MCP docs server configured (e.g., for React, Django, or Express):

You:   $codex-autoresearch
       Optimize our React component rendering performance

Codex: [during ideation, queries MCP docs server for React.memo,
       useMemo, and useCallback best practices]
       [uses documentation insights to generate better hypotheses]

The agent consults MCP docs automatically when it encounters framework-specific patterns it needs to understand better. No special configuration needed beyond having the MCP server available.

Database EXPLAIN queries during latency optimization

If you have an MCP database server configured:

You:   $codex-autoresearch
       Reduce /search endpoint p95 latency from 800ms to 200ms

Codex: [runs EXPLAIN via MCP database server to identify slow queries]
       [uses query plans to generate targeted index and query optimizations]

API testing during security audits

If you have an MCP API testing server configured:

You:   $codex-autoresearch Mode: security
       Audit our REST API for injection vulnerabilities

Codex: [uses MCP API server to send test payloads during audit]
       [validates findings with actual API responses, not just code analysis]

---

Choosing Verify and Guard Commands

The protocol is language-agnostic. Only the commands change.

By language

By metric type

Writing a good verify command

Requirements:

• Must output a single number (or a line containing a number Codex can extract)
• Must be deterministic (same input = same output)
• Must be fast (minutes, not hours -- fast verification = more experiments)
• Must not require user interaction

Compound guards

Chain multiple safety checks with &&:

Guard: npx tsc --noEmit && npm run test:unit && npm run lint

All must pass for the guard to pass.

Operator's Manual

How to get results from codex-autoresearch. Covers installation, the two-phase interaction model, every mode, and practical tips.

---

Installation

Recommended: install with the skill installer:

$skill-installer install https://github.com/leo-lilinxiao/codex-autoresearch

Manual copy still works:

git clone https://github.com/leo-lilinxiao/codex-autoresearch.git
cp -r codex-autoresearch your-project/.agents/skills/codex-autoresearch

Verify: open Codex in the target repo, type $, confirm codex-autoresearch appears.

See INSTALL.md for skill installer, manual copy, user-scope, and live-development options.

[!IMPORTANT]

For the smoothest foreground and background experience, start Codex with Full Access:

>

```bash

codex --dangerously-bypass-approvals-and-sandbox

```

>

Use this before starting autoresearch for the smoothest foreground and background experience.

---

How Interaction Works

Every invocation follows a two-phase model. Understanding these two phases is the single most important thing in this manual.

Phase 1: Setup (interactive)

You say one sentence. Codex scans the repo, fills in what it can, and asks you to confirm or clarify the rest. This is a conversation -- you can steer it, add constraints, or just say "go."

You:   $codex-autoresearch
       I want to get rid of all the `any` types in my TypeScript code

Codex: I found 47 `any` occurrences across src/**/*.ts.

       Confirmed:
       - Target: eliminate `any` types in src/**/*.ts
       - Results directory: `./autoresearch-results/`
       - Metric: `any` count (current: 47), direction: lower
       - Verify: grep count, Guard: tsc --noEmit

       Need to confirm:
       - Run mode: foreground or background?
       - Run until all gone, or cap at N iterations?
       - Any other safety checks beyond tsc?

       Choose a run mode, then reply "go" to start, or tell me what to change.

The wizard usually finishes in 1 to 3 rounds. It always asks at least one confirming question, even when it could infer everything.

For unattended runs, the wizard may also ask one safety question about rollback or workspace isolation before launch. After you say "go," it does not stop to ask more questions.

Phase 2: Execution (fully autonomous)

Once you say "go" (or "start", "launch", or any clear approval), the chosen run mode takes over. From this point on, Codex will never pause to ask you anything. If it hits ambiguity, it applies best practices and keeps going. In foreground it continues in the current session; in background it hands off so you can walk away, go to sleep, or work on something else. For that to hold in practice, launch Codex CLI with approvals / sandbox settings that will not interrupt git commit or revert commands. In a disposable or otherwise trusted repo, giving Codex fuller permissions is the simplest option.

The only things that stop the loop:

• You interrupt Codex
• The goal or configured stop condition is reached
• The iteration cap is reached (if you set one)
• A soft blocker handoff occurs after strategy exhaustion
• A hard blocker appears (verify command broken, repo corrupted, disk full, same crash 5+ times)

This boundary is absolute at the skill level. Everything before "go" can ask. Everything after "go" keeps running without new questions.

Once execution begins, keep the runtime contract tiny:

• baseline before init
• record every completed experiment before the next one starts
• use helper scripts for authoritative log/state updates

Continuity

Autoresearch prepares resume and background handoff support automatically when a run starts.

For troubleshooting, you can prepare it directly:

python3 /absolute/path/to/codex-autoresearch/scripts/autoresearch_hooks_ctl.py install

---

The Iteration Cycle

Every iterating mode (loop, debug, fix, security, ship) shares the same cycle:

  Pick hypothesis  -->  Edit files  -->  trial commit  -->  Run verify + guard
  (consult lessons,                                            |
   apply perspectives,                                     improved?
   filter by environment)                                 /         \
                                                        yes          no
                                                        /              \
                                                     KEEP           REVERT
                                                  (+lesson)            |
                                                      \              /
                                                       +-- Log -----+
                                                            |
                                                      Health check
                                                            |
                                                    3+ discards? --yes--> REFINE/PIVOT
                                                            |
                                                          repeat

1. Hypothesis -- one focused idea based on what worked, what failed, what is untried 2. Edit -- change files within the declared scope only 3. Trial commit -- create a scoped experiment commit before verification when the workspace is safe to isolate 4. Verify -- run the verify command, extract the metric value 5. Guard -- if set, run the guard command to check for regressions 6. Decide -- metric improved and guard passed = keep; otherwise revert 7. Log -- record the result before starting the next experiment

Revert uses the rollback strategy approved during setup. In a dedicated experiment branch/worktree with pre-launch approval, it may use git reset --hard HEAD~1; otherwise it uses git revert --no-edit HEAD.

Run artifacts should be updated by the helper scripts rather than hand-editing TSV or JSON. Use the skill-bundle path, not the target repo's own scripts/ directory. Here <skill-root> means the directory containing the loaded SKILL.md; in the common repo-local install this is .agents/skills/codex-autoresearch.

• python3 <skill-root>/scripts/autoresearch_init_run.py --repo <primary_repo> --workspace-root <workspace_root>
• python3 <skill-root>/scripts/autoresearch_record_iteration.py
• python3 <skill-root>/scripts/autoresearch_resume_check.py --repo <primary_repo>
• python3 <skill-root>/scripts/autoresearch_select_parallel_batch.py
• python3 <skill-root>/scripts/autoresearch_supervisor_status.py --repo <primary_repo>

Verify and Guard: two gates, two questions

A good pairing answers two different questions:

Verify: pytest --cov=src --cov-report=term 2>&1 | grep TOTAL | awk '{print $NF}'
        ^ "Did coverage go up?"

Guard:  npx tsc --noEmit
        ^ "Do types still compile?"

Another example:

Verify: node scripts/count-lint-warnings.js
        ^ "Did warning count go down?"

Guard:  npm run test:unit
        ^ "Do unit tests still pass?"

Guard is optional. Use it when improving one metric could hurt something else.

---

Configuration Fields

Codex infers these from your natural language input and repo context. You never need to write them -- the wizard handles translation. They are documented here for understanding.

Required (loop mode)

Optional

Bounded vs unbounded runs

By default the loop runs until you interrupt it. Tell Codex to cap it:

You:   Go, but only 10 iterations.

or:

You:   Run overnight, no limit.

When to use each:

• Overnight exploration -- unlimited. Let Codex try dozens of approaches.
• Focused fix -- 5-10 iterations. The problem space is small.
• Quick experiment -- 3-5 iterations. You just want to see if the approach works.

Bounded runs print a final summary comparing baseline to best result.

---

Modes

Seven modes, one invocation pattern: $codex-autoresearch followed by a sentence. Codex auto-detects which mode fits. You can also force a mode by saying it explicitly (e.g., "use debug mode").

loop

The default. Iterates toward a measurable target.

You:   $codex-autoresearch
       Our TypeScript codebase has 47 `any` types, eliminate them all

Codex: [scans repo, confirms target, asks about run mode and iteration cap]

You:   Background, go. Run overnight.

Codex: Starting background run -- baseline: 47. Detached runtime is now iterating.
       ...
       Iteration 1: replaced any in auth module -> 41 (-6) KEEP
       Iteration 2: generic wrapper attempt -> 49 (+8) DISCARD
       Iteration 3: narrowed API handlers -> 38 (-3) KEEP
       ...

Reference: references/autonomous-loop-protocol.md Thin runtime guide: references/loop-workflow.md

plan

Converts a vague goal into a concrete loop configuration. Use when you know what you want but not how to measure it.

You:   $codex-autoresearch
       I want to make our API faster but I don't know where to start

Codex: I scanned the repo. API layer is in src/api/ with Express + Prisma.

       Need to confirm:
       - What matters more: p95 latency, throughput, or cold start?
       - Should I benchmark the whole API or specific endpoints?

You:   p95 latency, the /search endpoint is the worst.

Codex: [proposes config, dry-runs the verify command, outputs ready-to-use block]

Plan mode is read-only -- it never modifies your code.

Reference: references/plan-workflow.md

debug

Evidence-driven bug hunting. Each iteration tests one falsifiable hypothesis.

You:   $codex-autoresearch
       API returns 503 randomly under load, no idea why

Codex: I see connection pooling in src/db/pool.ts, rate limiting in
       src/middleware/, and 3 async handlers without error boundaries.

       Need to confirm:
       - Run mode: foreground or background?
       - When did this start? After a specific change, or always?
       - If I find the cause, should I also fix it?

You:   Foreground. Started after the pool refactor last week. Find cause first.

Codex: Starting foreground investigation.
       ...
       Hypothesis 1: pool exhaustion under concurrent requests
         Evidence: pool.ts max=10, /search handler holds 3 connections
         Result: CONFIRMED -- pool saturates at 4 concurrent /search calls
       ...

Debug mode produces a findings directory with confirmed causes, disproven hypotheses, and recommended fixes.

To repair the findings afterward, start a new invocation:

You:   $codex-autoresearch
       Fix the bugs you found in the last debug session

Codex reads the debug output directory and enters fix mode automatically.

Reference: references/debug-workflow.md

fix

Iteratively repairs errors until the count reaches zero. Auto-detects what is broken (tests, types, lint, build).

You:   $codex-autoresearch
       pytest is failing, 12 tests broken after the refactor

Codex: I see 12 failures across tests/.

       Confirmed:
       - Target: make all pytest tests pass
       - Current: 12 failures

       Need to confirm:
       - Run mode: foreground or background?
       - Should I also guard with ruff to avoid introducing lint issues?
       - Fix all 12, or focus on a specific module first?

You:   Foreground. Fix all, yes guard with ruff. Go.

Codex: Starting foreground run -- baseline: 12 failures.
       ...
       Iteration 1: fixed import path in test_auth.py -> 10 (-2) KEEP
       ...

Fix mode stops automatically when the error count reaches zero.

Reference: references/fix-workflow.md

security

Read-only structured audit using STRIDE threat modeling, OWASP Top 10, and red-team analysis. Every finding requires code evidence -- no theoretical vulnerabilities.

You:   $codex-autoresearch
       Check our API for injection vulnerabilities

Codex: Confirmed:
       - Scope: src/api/ and src/middleware/ (14 files)
       - Focus: SQL injection, XSS, input sanitization

       Need to confirm:
       - Run mode: foreground or background?
       - Report only, or also fix critical findings?
       - Should I also cover auth/access control?

You:   Foreground. Report first, and yes cover auth too.

Codex: Starting foreground audit.
       ...
       Finding S-1 [HIGH]: SQL injection in src/api/search.ts:42
         Raw user input passed to query builder without parameterization
         Exploitation: POST /search with payload `'; DROP TABLE users;--`
       ...

Security mode is read-only by default. To also repair findings, say so during setup:

You:   Find vulnerabilities and fix the critical ones.

Codex will audit first, then switch to fix mode for Critical/High findings.

Reference: references/security-workflow.md

ship

Gated release verification. Auto-detects what you are shipping (PR, deployment, release) and generates a checklist.

Under the hood, ship mode still resolves a shipment scope, a readiness metric, and a mechanical verify command before the chosen interactive run mode begins.

You:   $codex-autoresearch
       Ship it

Codex: Detected: PR to main with 3 commits.

       Confirmed:
       - Type: code PR
       - Target: main branch

       Need to confirm:
       - Run mode: foreground or background?
       - Dry run first, or go live?
       - Post-ship monitoring? (5 min / 15 min / skip)

You:   Foreground, dry run first.

External actions (deploy, publish, merge) must be confirmed during this setup phase. If not confirmed before "go," they are skipped and logged as blockers.

Reference: references/ship-workflow.md

---

Mode Chaining

Modes compose naturally through sequential invocations:

Find then fix:

You:   $codex-autoresearch
       API returns 503 randomly under load
       [debug mode runs, produces findings]

You:   $codex-autoresearch
       Fix the bugs you just found
       [fix mode runs, imports debug findings]

Plan then execute:

You:   $codex-autoresearch
       I want to reduce our API latency but not sure how to measure it
       [plan mode runs, produces config]

You:   $codex-autoresearch
       [paste the config plan generated, or just say "run the plan you made"]

Audit then remediate:

You:   $codex-autoresearch
       Audit the auth system for vulnerabilities, then fix anything critical
       [security mode audits, then automatically switches to fix mode]

---

Results Log

Every iteration is recorded in autoresearch-results/results.tsv:

iteration  commit   metric  delta   status    description
0          a1b2c3d  47      0       baseline  initial any count
1          b2c3d4e  41      -6      keep      replace any in auth module with strict types
2          -        49      +8      discard   generic wrapper introduced new anys
3          d4e5f6g  38      -3      keep      type-narrow API response handlers

Progress summaries print every 5 iterations. Bounded runs print a final baseline-to-best summary.

The TSV file is the real audit trail -- not the git history (failed experiments are reverted from git but preserved in the log).

The workspace-owned autoresearch-results/ directory and repo-local autoresearch pointers are treated as autoresearch-owned artifacts: they stay uncommitted and are not staged as experiment changes.

---

Workspace Requirements

The loop commits and reverts repeatedly. This requires a clean workspace.

If unrelated uncommitted changes exist:

• The loop will not start
• Use plan mode instead (read-only, no git requirements)
• Or isolate the work in a clean branch or worktree

---

Output Artifacts

---

Safety Model

---

Cross-Run Learning

Every iterating run except exec extracts structured lessons and persists them to autoresearch-results/lessons.md (alongside the results log, never committed). Future runs consult lessons to bias hypothesis generation. exec may read existing lessons, but it does not create or update them.

How it works:

• After every kept iteration: positive lesson (what worked and why)
• After every PIVOT: strategic lesson (what was abandoned and why)
• At run completion: summary lesson (best strategy family for this goal type)
• Cap: 50 entries. Older entries are summarized with time decay.

Lessons carry across runs and across goals. A lesson from optimizing test coverage can inform a later run optimizing build warnings if the strategy families overlap.

---

Smart Stuck Recovery (PIVOT / REFINE)

The loop uses a graduated escalation system instead of blind retrying:

1. REFINE (3 consecutive discards): Adjust within current strategy -- different file, different technique, different granularity. Consult lessons for similar past failures.

2. PIVOT (5 consecutive discards): Abandon current strategy entirely. Re-read everything, choose a fundamentally different approach. Extract a strategic lesson.

3. Web Search (2 PIVOTs without improvement): Search the web for solutions if available. Results are treated as hypotheses and verified mechanically.

4. Soft Blocker (3 PIVOTs without improvement): Print a warning, stop the current run, and report that human review, broader scope, or a better metric is needed.

A single successful keep resets all escalation counters to zero.

---

Parallel Experiments

When enabled during the wizard, the loop can test multiple hypotheses per iteration using subagent workers in isolated git worktrees:

• The orchestrator generates N hypotheses (max 3).
• Each worker applies one hypothesis, runs verify, and reports results.
• The orchestrator picks the best result, merges it, and discards the rest.
• If no result improved, it counts as a single discard for PIVOT tracking.

Parallel mode is suggested during the wizard when the environment has enough resources (CPU >= 4, RAM >= 8GB, sufficient disk). Falls back to serial if worktrees are unsupported.

---

Session Resume

If you interrupt a run and come back later, Codex can resume from where you left off:

• It first validates autoresearch-results/state.json, the primary recovery source, against the retained-state summary reconstructed from autoresearch-results/results.tsv.
• autoresearch-results/lessons.md is still read as context, but it is not the primary resume source.
• Foreground resume uses autoresearch-results/results.tsv plus autoresearch-results/state.json.
• Direct detached-runtime resume still requires an existing autoresearch-results/launch.json.
• If state is consistent: resumes immediately, no wizard needed. Background resume additionally requires the launch manifest.
• If state is partially consistent: runs a mini-wizard (1 round) to re-confirm.
• If state is inconsistent, the launch manifest is missing, or the goal has changed: starts fresh and archives the prior persistent run-control artifacts.

---

Long Run Stability

Long-running sessions (20+ iterations) may experience context drift when the CLI compacts the conversation to stay within context limits. The skill includes three layers of defense:

Automatic Re-Anchoring

Every 10 iterations (or more frequently after compaction), the agent runs a Protocol Fingerprint Check -- a zero-cost internal self-test that verifies it still remembers the runtime checklist and selected mode workflow. If any item fails, the agent re-reads the loaded runtime docs from disk before continuing. These events are marked with [RE-ANCHOR] in the results log.

You do not need to do anything to enable this. It runs automatically as part of Phase 8.7 in the iteration cycle.

Interactive Run Modes

Use $codex-autoresearch for interactive runs.

1. Start the skill and describe the goal naturally. 2. Answer the confirmation questions. 3. Choose foreground or background. 4. Reply go. 5. In foreground, Codex keeps the loop in the current session. autoresearch-results/results.tsv, autoresearch-results/state.json, autoresearch-results/context.json, and lessons are created. 6. In background, Codex writes autoresearch-results/launch.json and starts the detached runtime controller automatically. The two modes share the same loop protocol and repo/scope semantics, but they are mutually exclusive for a given workspace/run. Do not keep both modes active against the same Results directory at once. 7. If you resume an existing interactive run in the other mode, continue through $codex-autoresearch; shared state is synchronized before the run continues. 8. For a new interactive run, the default workspace root comes from the launch context. If you started Codex inside a git repo, that repo root is the default workspace root. If you started Codex outside a git repo, the current launch directory is the default workspace root. 9. Single-repo runs are still the default. In that case the declared scope applies only to the primary repo, while run artifacts stay in that launch-context workspace under ./autoresearch-results/. 10. Codex should not silently widen the workspace root to a parent directory just because sibling repos, old autoresearch-results/, or a broader folder layout exist. If a wider shared workspace is truly intended, the confirmation summary should make that explicit and show the resulting Results directory before launch. 11. If the experiment spans multiple repos, either mode can declare companion repos with their own scopes. Run artifacts stay under the chosen workspace-owned autoresearch-results/ directory, while each managed repo stores a repo-local pointer to that canonical context. Script-level entrypoints represent this with repeated --companion-repo-scope PATH=SCOPE flags. The TSV commit column remains the primary repo commit; companion-repo commit provenance lives in autoresearch-results/state.json. 12. Each background runtime cycle launches a non-interactive codex exec session with the runtime prompt supplied on stdin. Background launch manifests default to danger_full_access, so detached sessions run with --dangerously-bypass-approvals-and-sandbox unless you explicitly choose the sandboxed workspace_write path. Start background runs from a trusted Full Access Codex session. 13. Before each background detached session or relaunch, the runtime controller runs autoresearch_health_check.py and autoresearch_commit_gate.py so integrity and scope safety are enforced at the control-plane boundary across all managed repos. 14. If background codex exec itself cannot be launched, the runtime moves to needs_human instead of silently looking idle. 15. If an explicit stop request cannot actually terminate the detached runner, the runtime also moves to needs_human instead of pretending the run is fully stopped.

Foreground keeps iterating in the current session until a terminal condition, blocker, or interruption. Background continues through fresh Codex sessions in the background until a terminal condition, blocker, or explicit stop request.

Use the same skill entry for follow-up control:

• ask for status -> background mode only; the skill reads the runtime controller state
• ask to stop -> background mode only; the skill stops the runtime controller
• ask to resume -> the skill checks launch/runtime state and continues if safe

Advanced backend commands are still available for scripting or debugging:

If you are not automating or debugging the backend directly, ignore the commands below and keep using $codex-autoresearch.

python3 <skill-root>/scripts/autoresearch_resume_check.py --repo /path/to/repo
python3 <skill-root>/scripts/autoresearch_launch_gate.py --repo /path/to/repo
python3 <skill-root>/scripts/autoresearch_resume_prompt.py --repo /path/to/repo
python3 <skill-root>/scripts/autoresearch_supervisor_status.py --repo /path/to/repo
python3 <skill-root>/scripts/autoresearch_runtime_ctl.py status --repo /path/to/repo
python3 <skill-root>/scripts/autoresearch_runtime_ctl.py stop --repo /path/to/repo

---

Environment Awareness

At the start of every run, Codex probes the environment:

• CPU cores, RAM, disk space
• GPU/NPU detection (NVIDIA, Ascend, ROCm, Apple Silicon)
• Installed toolchains (Python, Node.js, Go, Rust, Java)
• Container detection (Docker, Kubernetes)
• Network availability

This data filters infeasible hypotheses (e.g., no GPU optimization without a GPU) and informs resource-appropriate suggestions during plan mode.

---

CI/CD Mode (exec)

Use exec only for CI or scripted automation. Most interactive work should use $codex-autoresearch with foreground or background mode. In exec, there is no wizard; the automation prompt must provide the run configuration upfront.

Differences from interactive mode:

• No wizard -- all config provided upfront in the codex exec prompt or via environment variables
• Always bounded (Iterations field is mandatory)
• JSON output (one line per iteration, completion summary at end)
• No web search, no parallel, no session resume
• Reads lessons if available, but does not write them
• Exit codes: 0 = improved, 1 = no improvement, 2 = hard blocker

Before using codex exec in CI, configure Codex CLI authentication in advance. In controlled automation environments, prefer codex exec --dangerously-bypass-approvals-and-sandbox ... so the verify command has the same full-access behavior as the managed runtime. For programmatic runs, API key authentication is the preferred option.

When the bundled helper scripts drive Mode: exec, do not manually rename old artifacts first. Let autoresearch_init_run.py --repo <primary_repo> --workspace-root <workspace_root> --mode exec ... perform its fresh-start archival, and keep autoresearch_exec_state.py --cleanup as the final serial helper step after the last autoresearch_record_iteration.py / autoresearch_select_parallel_batch.py call.

See references/exec-workflow.md for full details and CI integration examples.

---

Troubleshooting

The skill does not appear

• Confirm the folder is at .agents/skills/codex-autoresearch or ~/.agents/skills/codex-autoresearch
• Confirm SKILL.md exists at the root of that folder
• Confirm /skills lists codex-autoresearch

Codex starts without asking

This should not happen. Rule 1 requires at least one confirming question. If it does happen, the skill may not be loading correctly -- check the installation path.

The loop stops and asks a question

This should not happen after you say "go." If it does, report it as a bug. The two-phase boundary is a hard rule.

How do I see runtime status or stop a run?

Use $codex-autoresearch and ask for background status or stop. Foreground runs stay in the active session.

The verify command fails on the first run

Codex will attempt to fix it. If plan mode generated the config, it may dry-run the verify command when practical before outputting the block. If you wrote the verify command yourself, test it manually first.

The loop refuses to commit

• Check for unrelated uncommitted changes (git status)
• Isolate work in a clean branch or worktree
• Use plan mode first if the workspace is not clean

Can I use this without git?

Plan mode and security mode (read-only) work without git. The iterative loop requires git for its commit/revert safety model.

Can I use this with any language?

Yes. The protocol is language-agnostic. Only the verify and guard commands are domain-specific.

<p align="center"> <img src="../../image/banner.png" width="700" alt="Codex Autoresearch"> </p>

<h2 align="center"><b>Zielen. Iterieren. Ankommen.</b></h2>

<p align="center"> <i>Autonomes, zielgesteuertes Experimentieren für Codex.</i> </p>

<p align="center"> <a href="https://developers.openai.com/codex/skills"><img src="https://img.shields.io/badge/Codex-Skill-blue?logo=openai&logoColor=white" alt="Codex Skill"></a> <a href="https://github.com/leo-lilinxiao/codex-autoresearch"><img src="https://img.shields.io/github/stars/leo-lilinxiao/codex-autoresearch?style=social" alt="GitHub Stars"></a> <a href="../../LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT License"></a> </p>

<p align="center"> <a href="../../README.md">English</a> · <a href="README_ZH.md">🇨🇳 中文</a> · <a href="README_JA.md">🇯🇵 日本語</a> · <a href="README_KO.md">🇰🇷 한국어</a> · <a href="README_FR.md">🇫🇷 Français</a> · <b>🇩🇪 Deutsch</b> · <a href="README_ES.md">🇪🇸 Español</a> · <a href="README_PT.md">🇧🇷 Português</a> · <a href="README_RU.md">🇷🇺 Русский</a> </p>

---

Die Idee: Sagen Sie Codex, was Sie verbessern möchten, und gehen Sie. Er ändert Ihren Code, überprüft das Ergebnis, behält oder verwirft, und wiederholt. Sie kommen zurück zu einem Experimentprotokoll und einer besseren Codebasis.

Inspiriert von Karpathys autoresearch, verallgemeinert über ML hinaus auf alles, was sich mechanisch verifizieren lässt: Testabdeckung, Typfehler, Latenz, Lint-Warnungen, Sicherheitsbefunde, Release-Bereitschaft — wenn ein Befehl feststellen kann, ob es besser wurde, kann die Schleife darauf iterieren.

Schnellstart

[!IMPORTANT]

Starte Codex mit Full Access:

>

```bash

codex --dangerously-bypass-approvals-and-sandbox

```

>

Nutze dies vor autoresearch, damit foreground und background am reibungslosesten funktionieren.

# In Codex installieren (empfohlen)
$skill-installer install https://github.com/leo-lilinxiao/codex-autoresearch

Öffnen Sie Ihr Projekt und legen Sie los:

Du:    $codex-autoresearch
       Ich will alle `any`-Typen in meinem TypeScript-Code loswerden

Codex: Ich habe 47 `any`-Vorkommen in src/**/*.ts gefunden.
       Results-Verzeichnis: ./autoresearch-results/
       Metrik: `any`-Anzahl (aktuell: 47), Richtung: niedriger
       Verifikation: grep-Zählung + tsc --noEmit als guard
       Ausführungsmodus: foreground oder background?

Du:    Background, go. Lass es über Nacht laufen.

Codex: Starte Hintergrundlauf — Baseline: 47. Iteriere.

Starten Sie Background-Läufe aus einer vertrauenswürdigen Full Access Codex-Sitzung.

Jede Verbesserung baut auf. Jeder Fehlschlag wird zurückgesetzt. Alles wird protokolliert.

Manuelle Kopier-, Symlink- und User-Scope-Optionen stehen in INSTALL.md. Vollständiges Handbuch in GUIDE.md.

So funktioniert es

Du sagst einen Satz  →  Codex scannt & bestätigt  →  Du sagst "go"
                                                         |
                                          +--------------+--------------+
                                          |                             |
                                     foreground                    background
                                   (aktuelle Sitzung)          (abgekoppelt, über Nacht)
                                          |                             |
                                          +--------------+--------------+
                                                         |
                                                         v
                                               +-------------------+
                                               |   Die Schleife    |
                                               |                   |
                                               |  eine Sache ändern|
                                               |  trial commit     |
                                               |  verify ausführen |
                                               |  besser? behalten |
                                               |  schlechter? rev. |
                                               |  Ergebnis loggen  |
                                               |  wiederholen      |
                                               +-------------------+

Das war's. Sie wählen eines von beiden: Foreground behält die Schleife in Ihrer aktuellen Sitzung, Background übergibt sie an einen abgekoppelten Prozess, damit Sie schlafen können. Dieselbe Schleife, aber sie laufen nicht gleichzeitig.

Was Sie sagen vs was passiert

Im Hintergrund ordnet Codex Ihren Satz einem von 7 Modi zu (loop, plan, debug, fix, security, ship, exec). Sie müssen nie einen auswählen.

Was Codex automatisch ermittelt

Sie schreiben keine Konfiguration. Codex leitet alles aus Ihrem Satz und Ihrem Repo ab:

Vor dem Start zeigt Codex immer, was er gefunden hat, und bittet um Bestätigung. Dann wählen Sie foreground oder background und sagen „go". Standardmäßig bleibt das Results-Verzeichnis im Startkontext: Wenn Sie Codex in einem Git-Repo gestartet haben, ist dessen Repo-Root der Standard-Workspace-Root; wenn Sie Codex außerhalb eines Git-Repos gestartet haben, ist das aktuelle Startverzeichnis der Standard-Workspace-Root. Codex sollte dies nicht stillschweigend auf ein übergeordnetes Verzeichnis ausweiten, es sei denn, Sie bestätigen ausdrücklich einen größeren Multi-Repo-Workspace. Die Bestätigungsübersicht sollte vor dem Start immer das gewählte Results-Verzeichnis anzeigen.

Wenn es hakt

Statt blind zu wiederholen, eskaliert die Schleife:

Ein einziger Erfolg setzt alle Zähler zurück.

Ergebnisprotokoll

Jede Iteration wird in autoresearch-results/results.tsv aufgezeichnet:

iteration  commit   metric  delta   status    description
0          a1b2c3d  47      0       baseline  initial any count
1          b2c3d4e  41      -6      keep      replace any in auth module
2          -        49      +8      discard   generic wrapper introduced new anys
3          d4e5f6g  38      -3      keep      type-narrow API response handlers

Fehlgeschlagene Experimente werden in git zurückgesetzt, bleiben aber im Protokoll. Das Protokoll ist die eigentliche Audit-Spur, während autoresearch-results/state.json der Resume-Snapshot ist.

Weitere Funktionen

Details in GUIDE.md:

• Laufübergreifendes Lernen — Erkenntnisse aus vergangenen Läufen beeinflussen die zukünftige Hypothesengenerierung
• Parallele Experimente — bis zu 3 Hypothesen gleichzeitig über git worktrees testen
• Sitzungswiederaufnahme — unterbrochene Läufe setzen beim letzten konsistenten Zustand fort
• CI/CD-Modus (exec) — nicht-interaktiv, JSON-Ausgabe, für Automatisierungspipelines
• Doppelte Prüfung — getrenntes verify (hat es sich verbessert?) und guard (ist etwas kaputtgegangen?)

FAQ

Es macht nur kleine Änderungen. Kann es größere Ideen ausprobieren? Standardmäßig bevorzugt die Schleife kleine, überprüfbare Schritte — das ist beabsichtigt. Aber sie kann auch größer denken: Beschreiben Sie eine umfangreichere Hypothese in Ihrem Prompt (z.B. „ersetze den Attention-Mechanismus durch Linear Attention und führe die vollständige Evaluation durch"), und sie wird das als ein einzelnes Experiment verifizieren. Am besten funktioniert es, wenn der Mensch die Forschungsrichtung vorgibt und der Agent die intensive Ausführung und Analyse übernimmt.

Ist das eher für Engineering-Optimierung oder für Forschung? Am stärksten ist es, wenn Ziel und Metrik klar sind — Abdeckung erhöhen, Fehler reduzieren, Latenz senken. Wenn die Forschungsrichtung selbst noch unklar ist, nutzen Sie zuerst den plan-Modus zum Erkunden, dann wechseln Sie zu loop, sobald Sie wissen, was Sie messen wollen. Betrachten Sie es als Mensch-KI-Zusammenarbeit: Sie liefern das Urteil, der Agent liefert die Iterationsgeschwindigkeit.

Wie stoppe ich es? Foreground: Codex unterbrechen. Background: $codex-autoresearch und dann Stopp anfordern.

Kann es nach einer Unterbrechung fortsetzen? Ja. Es setzt automatisch von autoresearch-results/state.json fort.

Wie nutze ich es in CI? Mode: exec mit codex exec. Gesamte Konfiguration vorab, JSON-Ausgabe, Exit-Codes 0/1/2.

Dokumentation

Danksagungen

Aufgebaut auf Ideen von Karpathys autoresearch. Die Codex-Skills-Plattform stammt von OpenAI.

Citation

Wenn Sie Codex Autoresearch in Ihrer Arbeit verwenden, zitieren Sie es bitte so:

@misc{codex-autoresearch,
  author = {Li, Linxiao},
  title = {Codex Autoresearch: Autonomous Goal-Driven Experimentation for Codex},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/leo-lilinxiao/codex-autoresearch}
}

Star History

<a href="https://www.star-history.com/?repos=leo-lilinxiao%2Fcodex-autoresearch&type=timeline&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&legend=top-left" /> </picture> </a>

Lizenz

MIT — siehe LICENSE.

<p align="center"> <img src="../../image/banner.png" width="700" alt="Codex Autoresearch"> </p>

<h2 align="center"><b>Apuntar. Iterar. Llegar.</b></h2>

<p align="center"> <i>Experimentación autónoma orientada a objetivos para Codex.</i> </p>

<p align="center"> <a href="https://developers.openai.com/codex/skills"><img src="https://img.shields.io/badge/Codex-Skill-blue?logo=openai&logoColor=white" alt="Codex Skill"></a> <a href="https://github.com/leo-lilinxiao/codex-autoresearch"><img src="https://img.shields.io/github/stars/leo-lilinxiao/codex-autoresearch?style=social" alt="GitHub Stars"></a> <a href="../../LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT License"></a> </p>

<p align="center"> <a href="../../README.md">English</a> · <a href="README_ZH.md">🇨🇳 中文</a> · <a href="README_JA.md">🇯🇵 日本語</a> · <a href="README_KO.md">🇰🇷 한국어</a> · <a href="README_FR.md">🇫🇷 Français</a> · <a href="README_DE.md">🇩🇪 Deutsch</a> · <b>🇪🇸 Español</b> · <a href="README_PT.md">🇧🇷 Português</a> · <a href="README_RU.md">🇷🇺 Русский</a> </p>

---

La idea: dile a Codex qué quieres mejorar y vete. Modifica tu código, verifica el resultado, conserva o descarta, y repite. Vuelves a un registro de experimentos y un código mejor.

Inspirado en autoresearch de Karpathy, generalizado más allá de ML a todo lo que se pueda verificar mecánicamente: cobertura de tests, errores de tipos, latencia, advertencias de lint, hallazgos de seguridad, preparación de releases — si un comando puede determinar si mejoró, el bucle puede iterar sobre ello.

Inicio rápido

[!IMPORTANT]

Inicia Codex con Full Access:

>

```bash

codex --dangerously-bypass-approvals-and-sandbox

```

>

Úsalo antes de iniciar autoresearch para la experiencia más fluida en foreground y background.

# Instalar en Codex (recomendado)
$skill-installer install https://github.com/leo-lilinxiao/codex-autoresearch

Abre tu proyecto y adelante:

Tú:    $codex-autoresearch
       Quiero eliminar todos los tipos `any` de mi código TypeScript

Codex: Encontré 47 ocurrencias de `any` en src/**/*.ts.
       Directorio Results: ./autoresearch-results/
       Métrica: cantidad de `any` (actual: 47), dirección: menor
       Verificación: conteo grep + tsc --noEmit como guard
       Modo de ejecución: ¿foreground o background?

Tú:    Background, go. Déjalo corriendo toda la noche.

Codex: Iniciando ejecución en segundo plano — línea base: 47. Iterando.

Para ejecuciones background, inicia Codex desde una sesión Full Access de confianza.

Cada mejora se acumula. Cada fallo se revierte. Todo queda registrado.

Opciones de copia manual, symlink y alcance de usuario en INSTALL.md. Manual completo en GUIDE.md.

Cómo funciona

Dices una frase  →  Codex analiza y confirma  →  Dices "go"
                                                      |
                                       +--------------+--------------+
                                       |                             |
                                  foreground                    background
                                (sesión actual)             (separado, toda la noche)
                                       |                             |
                                       +--------------+--------------+
                                                      |
                                                      v
                                            +-------------------+
                                            |    El bucle       |
                                            |                   |
                                            |  modificar algo   |
                                            |  trial commit     |
                                            |  ejecutar verify  |
                                            |  ¿mejoró? guardar |
                                            |  ¿empeoró? revert |
                                            |  registrar result.|
                                            |  repetir          |
                                            +-------------------+

Eso es todo. Eliges uno: foreground mantiene el bucle en tu sesión actual, background lo delega a un proceso separado para que puedas dormir. El mismo bucle en ambos casos, pero no se ejecutan a la vez.

Lo que dices vs lo que pasa

Tras bambalinas, Codex mapea tu frase a uno de 7 modos (loop, plan, debug, fix, security, ship, exec). Nunca necesitas elegir uno.

Lo que Codex deduce automáticamente

No escribes configuración. Codex infiere todo a partir de tu frase y tu repositorio:

Antes de empezar, Codex siempre muestra lo que encontró y pide confirmación. Luego eliges foreground o background y dices «go». Por defecto, el directorio Results se queda en el contexto de arranque: si iniciaste Codex dentro de un repo git, la raíz de ese repo es el workspace root por defecto; si lo iniciaste fuera de un repo git, el directorio actual de arranque es el workspace root por defecto. Codex no debería ampliarlo silenciosamente a un directorio padre salvo que confirmes explícitamente un workspace multi-repo más amplio. El resumen de confirmación siempre debería mostrar el directorio Results elegido antes de lanzar.

Cuando se atasca

En lugar de reintentar a ciegas, el bucle escala:

Un solo éxito reinicia todos los contadores.

Registro de resultados

Cada iteración se registra en autoresearch-results/results.tsv:

iteration  commit   metric  delta   status    description
0          a1b2c3d  47      0       baseline  initial any count
1          b2c3d4e  41      -6      keep      replace any in auth module
2          -        49      +8      discard   generic wrapper introduced new anys
3          d4e5f6g  38      -3      keep      type-narrow API response handlers

Los experimentos fallidos se revierten en git pero permanecen en el registro. El registro es la verdadera pista de auditoría, mientras que autoresearch-results/state.json es la instantánea de reanudación.

Más funcionalidades

Detalles completos en GUIDE.md:

• Aprendizaje entre ejecuciones — las lecciones de ejecuciones pasadas orientan la generación futura de hipótesis
• Experimentos paralelos — prueba hasta 3 hipótesis simultáneamente mediante git worktrees
• Reanudación de sesión — las ejecuciones interrumpidas continúan desde el último estado consistente
• Modo CI/CD (exec) — no interactivo, salida JSON, para pipelines de automatización
• Verificación de doble puerta — verify (¿mejoró?) y guard (¿se rompió algo?) separados

FAQ

Solo hace cambios pequeños. ¿Puede intentar ideas más grandes? Por defecto el bucle favorece pasos pequeños y verificables — es intencional. Pero puede ir más grande: describe una hipótesis más amplia en tu prompt (ej: "reemplaza el mecanismo de attention por linear attention y ejecuta la evaluación completa"), y lo tratará como un solo experimento a verificar. El mejor uso: el humano define la dirección de investigación, el agente se encarga de la ejecución y análisis intensivos.

¿Es más para optimización de ingeniería o para investigación? Es más fuerte cuando el objetivo y la métrica están claros — subir cobertura, reducir errores, bajar latencia. Si la dirección de investigación es incierta, usa primero el modo plan para explorar, luego cambia a loop cuando sepas qué medir. Piénsalo como colaboración humano-IA: tú aportas el criterio, el agente aporta la velocidad de iteración.

¿Cómo lo detengo? Foreground: interrumpe Codex. Background: $codex-autoresearch y pide que se detenga.

¿Puede reanudar tras una interrupción? Sí. Reanuda automáticamente desde autoresearch-results/state.json.

¿Cómo lo uso en CI? Mode: exec con codex exec. Toda la configuración por adelantado, salida JSON, códigos de salida 0/1/2.

Documentación

Agradecimientos

Construido sobre ideas de autoresearch de Karpathy. La plataforma Codex skills es de OpenAI.

Citation

Si usas Codex Autoresearch en tu trabajo, cítalo así:

@misc{codex-autoresearch,
  author = {Li, Linxiao},
  title = {Codex Autoresearch: Autonomous Goal-Driven Experimentation for Codex},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/leo-lilinxiao/codex-autoresearch}
}

Star History

<a href="https://www.star-history.com/?repos=leo-lilinxiao%2Fcodex-autoresearch&type=timeline&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&legend=top-left" /> </picture> </a>

Licencia

MIT — ver LICENSE.

<p align="center"> <img src="../../image/banner.png" width="700" alt="Codex Autoresearch"> </p>

<h2 align="center"><b>Viser. Itérer. Aboutir.</b></h2>

<p align="center"> <i>Expérimentation autonome orientée objectif pour Codex.</i> </p>

<p align="center"> <a href="https://developers.openai.com/codex/skills"><img src="https://img.shields.io/badge/Codex-Skill-blue?logo=openai&logoColor=white" alt="Codex Skill"></a> <a href="https://github.com/leo-lilinxiao/codex-autoresearch"><img src="https://img.shields.io/github/stars/leo-lilinxiao/codex-autoresearch?style=social" alt="GitHub Stars"></a> <a href="../../LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT License"></a> </p>

<p align="center"> <a href="../../README.md">English</a> · <a href="README_ZH.md">🇨🇳 中文</a> · <a href="README_JA.md">🇯🇵 日本語</a> · <a href="README_KO.md">🇰🇷 한국어</a> · <b>🇫🇷 Français</b> · <a href="README_DE.md">🇩🇪 Deutsch</a> · <a href="README_ES.md">🇪🇸 Español</a> · <a href="README_PT.md">🇧🇷 Português</a> · <a href="README_RU.md">🇷🇺 Русский</a> </p>

---

L'idée : dites à Codex ce que vous voulez améliorer, puis partez. Il modifie votre code, vérifie le résultat, conserve ou annule, et recommence. Vous revenez avec un journal d'expériences et un code amélioré.

Inspiré par autoresearch de Karpathy, généralisé au-delà du ML à tout ce qui se vérifie mécaniquement : couverture de tests, erreurs de types, latence, avertissements lint, failles de sécurité, état de préparation au déploiement — si une commande peut dire si ça s'est amélioré, la boucle peut itérer dessus.

Démarrage rapide

[!IMPORTANT]

Démarrez Codex avec Full Access :

>

```bash

codex --dangerously-bypass-approvals-and-sandbox

```

>

Utilisez cette commande avant autoresearch pour l'expérience foreground et background la plus fluide.

# Installation dans Codex (recommandée)
$skill-installer install https://github.com/leo-lilinxiao/codex-autoresearch

Ouvrez votre projet et lancez-vous :

Vous:  $codex-autoresearch
       Je veux éliminer tous les types `any` dans mon code TypeScript

Codex: J'ai trouvé 47 occurrences de `any` dans src/**/*.ts.
       Répertoire Results : ./autoresearch-results/
       Métrique : nombre de `any` (actuel : 47), direction : diminuer
       Vérification : comptage grep + tsc --noEmit comme guard
       Mode d'exécution : foreground ou background ?

Vous:  Background, go. Laisse tourner toute la nuit.

Codex: Lancement en arrière-plan — référence : 47. Itération en cours.

Pour les exécutions background, démarrez Codex depuis une session Full Access de confiance.

Chaque amélioration s'accumule. Chaque échec est annulé. Tout est journalisé.

Options de copie manuelle, de symlink et d'installation utilisateur dans INSTALL.md. Manuel complet dans GUIDE.md.

Comment ça fonctionne

Vous dites une phrase  →  Codex analyse et confirme  →  Vous dites "go"
                                                            |
                                             +--------------+--------------+
                                             |                             |
                                        foreground                    background
                                      (session en cours)           (détaché, toute la nuit)
                                             |                             |
                                             +--------------+--------------+
                                                            |
                                                            v
                                                  +-------------------+
                                                  |    La boucle      |
                                                  |                   |
                                                  |  modifier un élém.|
                                                  |  trial commit     |
                                                  |  lancer verify    |
                                                  |  amélioré ? garder|
                                                  |  dégradé ? revert |
                                                  |  journaliser      |
                                                  |  recommencer      |
                                                  +-------------------+

C'est tout. Vous choisissez l'un ou l'autre : foreground garde la boucle dans votre session en cours, background la délègue à un processus détaché pour que vous puissiez dormir. Même boucle dans les deux cas, mais ils ne tournent pas en même temps.

Ce que vous dites vs ce qui se passe

En coulisses, Codex associe votre phrase à l'un des 7 modes (loop, plan, debug, fix, security, ship, exec). Vous n'avez jamais besoin d'en choisir un.

Ce que Codex déduit automatiquement

Pas besoin d'écrire de configuration. Codex infère tout à partir de votre phrase et de votre dépôt :

Avant de commencer, Codex montre toujours ce qu'il a trouvé et demande confirmation. Ensuite vous choisissez foreground ou background et dites « go ». Par défaut, le répertoire Results reste dans le contexte de lancement : si vous avez démarré Codex dans un dépôt git, la racine de ce dépôt est le workspace root par défaut ; si vous l'avez démarré hors d'un dépôt git, le répertoire de lancement courant est le workspace root par défaut. Codex ne doit pas l'élargir silencieusement à un répertoire parent sauf si vous confirmez explicitement un workspace multi-repo plus large. Le récapitulatif de confirmation doit toujours afficher le répertoire Results choisi avant le lancement.

Quand ça bloque

Au lieu de réessayer aveuglément, la boucle escalade :

Un seul succès réinitialise tous les compteurs.

Journal des résultats

Chaque itération est enregistrée dans autoresearch-results/results.tsv :

iteration  commit   metric  delta   status    description
0          a1b2c3d  47      0       baseline  initial any count
1          b2c3d4e  41      -6      keep      replace any in auth module
2          -        49      +8      discard   generic wrapper introduced new anys
3          d4e5f6g  38      -3      keep      type-narrow API response handlers

Les expériences échouées sont annulées dans git mais restent dans le journal. Le journal est la véritable piste d'audit, tandis que autoresearch-results/state.json est l'instantané de reprise.

Fonctionnalités supplémentaires

Détails complets dans GUIDE.md :

• Apprentissage inter-exécutions — les leçons des exécutions passées orientent la génération future d'hypothèses
• Expériences parallèles — teste jusqu'à 3 hypothèses simultanément via des git worktrees
• Reprise de session — les exécutions interrompues reprennent depuis le dernier état cohérent
• Mode CI/CD (exec) — non interactif, sortie JSON, pour les pipelines d'automatisation
• Double vérification — verify (y a-t-il amélioration ?) et guard (rien n'est cassé ?) séparés

FAQ

Il ne fait que de petits changements. Peut-il tenter des idées plus ambitieuses ? Par défaut, la boucle privilégie des pas petits et vérifiables — c'est voulu. Mais elle peut voir plus grand : décrivez une hypothèse plus large dans votre prompt (par ex. « remplace le mécanisme d'attention par une attention linéaire et lance l'évaluation complète »), et elle la traitera comme une seule expérience à vérifier. L'usage optimal : l'humain fixe la direction de recherche, l'agent assure l'exécution et l'analyse intensives.

C'est plutôt pour l'optimisation d'ingénierie ou pour la recherche ? C'est le plus efficace quand l'objectif et la métrique sont clairs — augmenter la couverture, réduire les erreurs, baisser la latence. Si la direction de recherche elle-même est incertaine, utilisez d'abord le mode plan pour explorer, puis passez à loop une fois que vous savez quoi mesurer. Voyez-le comme une collaboration humain-IA : vous apportez le jugement, l'agent apporte la vitesse d'itération.

Comment l'arrêter ? Foreground : interrompez Codex. Background : $codex-autoresearch puis demandez l'arrêt.

Peut-il reprendre après une interruption ? Oui. Il reprend automatiquement depuis autoresearch-results/state.json.

Comment l'utiliser en CI ? Mode: exec avec codex exec. Toute la configuration en amont, sortie JSON, codes de sortie 0/1/2.

Documentation

Remerciements

Construit sur les idées d'autoresearch de Karpathy. La plateforme Codex skills est développée par OpenAI.

Citation

Si vous utilisez Codex Autoresearch dans vos travaux, veuillez le citer ainsi :

@misc{codex-autoresearch,
  author = {Li, Linxiao},
  title = {Codex Autoresearch: Autonomous Goal-Driven Experimentation for Codex},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/leo-lilinxiao/codex-autoresearch}
}

Star History

<a href="https://www.star-history.com/?repos=leo-lilinxiao%2Fcodex-autoresearch&type=timeline&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&legend=top-left" /> </picture> </a>

Licence

MIT — voir LICENSE.

<p align="center"> <img src="../../image/banner.png" width="700" alt="Codex Autoresearch"> </p>

<h2 align="center"><b>狙う。回す。辿り着く。</b></h2>

<p align="center"> <i>Codex のための自律型目標駆動実験エンジン。</i> </p>

<p align="center"> <a href="https://developers.openai.com/codex/skills"><img src="https://img.shields.io/badge/Codex-Skill-blue?logo=openai&logoColor=white" alt="Codex Skill"></a> <a href="https://github.com/leo-lilinxiao/codex-autoresearch"><img src="https://img.shields.io/github/stars/leo-lilinxiao/codex-autoresearch?style=social" alt="GitHub Stars"></a> <a href="../../LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT License"></a> </p>

<p align="center"> <a href="../../README.md">English</a> · <a href="README_ZH.md">🇨🇳 中文</a> · <b>🇯🇵 日本語</b> · <a href="README_KO.md">🇰🇷 한국어</a> · <a href="README_FR.md">🇫🇷 Français</a> · <a href="README_DE.md">🇩🇪 Deutsch</a> · <a href="README_ES.md">🇪🇸 Español</a> · <a href="README_PT.md">🇧🇷 Português</a> · <a href="README_RU.md">🇷🇺 Русский</a> </p>

---

コンセプト：改善したいことを Codex に伝えて、あとは任せる。コードを修正し、結果を検証し、保持か破棄を判断し、繰り返す。戻ってくると、実験ログとより良いコードベースが待っています。

Karpathy の autoresearch に着想を得て、ML を超えて機械的に検証できるあらゆる目標に汎用化：テストカバレッジ、型エラー、レイテンシ、lint 警告、セキュリティ問題、リリース準備 — コマンドで改善を判定できるなら、ループが反復できます。

クイックスタート

[!IMPORTANT]

Full Access で Codex を起動することを推奨します：

>

```bash

codex --dangerously-bypass-approvals-and-sandbox

```

>

autoresearch を始める前にこのコマンドで起動すると、foreground と background が最もスムーズに動きます。

# Codex にインストール（推奨）
$skill-installer install https://github.com/leo-lilinxiao/codex-autoresearch

プロジェクトで開きます：

あなた: $codex-autoresearch
        TypeScript コードの any 型を全て除去してほしい

Codex:  src/**/*.ts に 47 個の `any` が見つかりました。
        Results ディレクトリ: ./autoresearch-results/
        指標：any の出現回数（現在 47）、方向：減少
        検証：grep カウント + tsc --noEmit ガード
        実行モード：foreground と background のどちらにしますか？

あなた: Background、go。一晩中走らせて。

Codex:  background 実行を開始 — ベースライン：47。反復中。

background 実行は、信頼できる Full Access の Codex セッションから開始してください。

改善は蓄積され、失敗はロールバックされ、全てが記録されます。

手動コピー、symlink、ユーザースコープの方法は INSTALL.md、完全な操作マニュアルは GUIDE.md を参照。

仕組み

一文で伝える  →  Codex がスキャン・確認  →  "go" と言う
                                              |
                                 +------------+------------+
                                 |                         |
                            foreground                background
                          (現在のセッション)        (バックグラウンド、一晩)
                                 |                         |
                                 +------------+------------+
                                              |
                                              v
                                    +-------------------+
                                    |    コアループ      |
                                    |                   |
                                    |  1つ変更する      |
                                    |  trial commit     |
                                    |  検証を実行       |
                                    |  改善？ → 保持    |
                                    |  悪化？ → 元に戻す|
                                    |  結果を記録       |
                                    |  繰り返す         |
                                    +-------------------+

これだけです。どちらか一つを選びます：foreground は現在のセッションでループを実行し、background はバックグラウンドプロセスに引き継いで席を外せます。同じループですが、同時には実行できません。

あなたの一言 vs 何が起こるか

裏側では、Codex が 7 つのモード（loop、plan、debug、fix、security、ship、exec）のいずれかにマッピングします。モードを選ぶ必要はありません。

Codex が自動で把握すること

設定を書く必要はありません。Codex があなたの言葉とリポジトリから全てを推論します：

開始前に、Codex は常に検出した内容を提示し、確認を求めます。その後 foreground か background を選んで "go" と言います。 デフォルトでは、Results ディレクトリは起動コンテキストに置かれます。Codex を git リポジトリ内で起動した場合はそのリポジトリルートが既定の workspace root になり、git リポジトリ外で起動した場合は現在の起動ディレクトリが既定の workspace root になります。より広いマルチリポジトリ workspace を明示的に確認しない限り、Codex が黙って親ディレクトリへ広げるべきではありません。起動前の確認サマリーには、選ばれた Results ディレクトリを必ず表示するべきです。

スタックしたとき

盲目的にリトライせず、段階的にエスカレートします：

1 回の成功で全てのカウンターがリセットされます。

結果ログ

各イテレーションは autoresearch-results/results.tsv に記録されます：

iteration  commit   metric  delta   status    description
0          a1b2c3d  47      0       baseline  initial any count
1          b2c3d4e  41      -6      keep      replace any in auth module
2          -        49      +8      discard   generic wrapper introduced new anys
3          d4e5f6g  38      -3      keep      type-narrow API response handlers

失敗した実験は git からリバートされますが、ログには残ります。ログが本当の監査証跡であり、autoresearch-results/state.json は再開用スナップショットです。

その他の機能

以下は GUIDE.md で詳しく説明しています：

• クロスラン学習 — 過去の実行からの教訓が将来の仮説生成に影響
• 並列実験 — git worktree で最大 3 つの仮説を同時にテスト
• セッション再開 — 中断された実行は最後の一貫した状態から再開
• CI/CD モード (exec) — 非対話、JSON 出力、自動化パイプライン向け
• 二重ゲート検証 — verify（改善したか？）と guard（他に壊れていないか？）を分離

FAQ

毎回小さな変更しかしない。もっと大きなアイデアを試せる？ デフォルトでは小さく検証可能なステップを好みます — これは設計通りです。しかしもっと大きなこともできます：プロンプトでより大きな仮説を記述すれば（例：「attention メカニズムを linear attention に置き換えて完全な eval を実行して」）、それを一つの実験として検証します。人が研究の方向を決め、エージェントが実行と分析を担当するのが最適な使い方です。

これは工学的最適化向き？それとも研究向き？ 目標と指標が明確なときに最も強力です — カバレッジを上げる、エラーを減らす、レイテンシを下げる。研究の方向自体が不確かな場合は、まず plan モードで探索し、何を測るか決まったら loop に切り替えてください。人間とAIの協業と考えてください：あなたが判断を提供し、エージェントが反復速度を提供します。

どうやって止める？ Foreground：Codex を中断。Background：$codex-autoresearch で停止を依頼。

中断後に再開できる？ はい。autoresearch-results/state.json から自動的に再開します。

CI で使うには？ Mode: exec と codex exec。全設定を事前に指定、JSON 出力、終了コード 0/1/2。

ドキュメント

謝辞

Karpathy の autoresearch の理念を基に構築。Codex skills プラットフォームは OpenAI 提供。

Citation

Codex Autoresearch を研究や開発で使用した場合は、次の形式で引用してください：

@misc{codex-autoresearch,
  author = {Li, Linxiao},
  title = {Codex Autoresearch: Autonomous Goal-Driven Experimentation for Codex},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/leo-lilinxiao/codex-autoresearch}
}

Star History

<a href="https://www.star-history.com/?repos=leo-lilinxiao%2Fcodex-autoresearch&type=timeline&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=leo-lilinxiao/codex-autoresearch&type=timeline&legend=top-left" /> </picture> </a>

ライセンス

MIT — LICENSE を参照。