autoresearch-claude-code skill
autoresearch drives an agent through an experiment loop with a fixed benchmark and budget, committing only measured improvements.
- 350 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent edits code and commits in a loop on its own; the Codex supervisor can run unattended.
- Scorer protection does not replace a sandbox.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/autoresearch-claude-codeDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent edits code and commits in a loop on its own; the Codex supervisor can run unattended.
- Scorer protection does not replace a sandbox.
This is third-party code. Review the repository files before installing.
What it does
The `autoresearch` skill for Claude Code and Codex sets a goal, a fixed benchmark and the files that may change. The agent tries edits, measures the result, commits confirmed improvements and logs failed ideas. State lives in JSONL, and noise calibration and correctness checks belong to the protocol. Claude Code gets a Stop hook; Codex gets a bounded `codex_loop.py` supervisor with turn and time limits and protection for scorer files.
Who it is for. Developers and researchers who have a numeric metric: test runtime, build speed, model quality.
Good fit when
- Test runtime must shrink and a script measures it.
- A model is tuned against a metric with a held-out split.
- Optimisation ideas are tried overnight with a limit of 20 runs.
- Experiments run in a separate worktree, leaving the main branch alone.
Not a fit when
- There is no metric and success is judged by eye.
- You need a sandbox against a hostile agent; scorer protection does not replace one.
- Installing on Windows without WSL; the README supports Linux and macOS.
Example request
Reduce test suite runtime within at most 20 runs, with a fixed benchmark and a list of editable files.Limitations
Python 3.10 or newer, Bash and Git are required; WSL is suggested on Windows. Limits count experiments, not tokens or money, so calibration and confirmation runs add cost. Scorer protection is not a sandbox against a hostile agent. The benchmark needs its own timeout, as the Stop hook checks the budget only at turn boundaries. The authors call the historical R² gain in the README example unvalidated.
How to disable. Run `./uninstall.sh --claude`, `--codex` or `--all`; it removes only its own symlinks and exact hook entries. To pause without removing, create the `.autoresearch-off` file.
FAQ
How do I start a loop in Claude Code?
After manual install, call `/autoresearch` with a goal. When loaded as a plugin the command is `/autoresearch:autoresearch`.
What about Codex?
Invoke the skill with `$autoresearch` and a goal. For unattended work, first initialise and pause the session, review the baseline and run `codex_loop.py --dry-run`.
What counts as an improvement?
A strict improvement beyond the noise floor with passing correctness checks. Changing the evaluation definition starts a new segment.
Is an MCP server required?
No. The protocol is a skill with standard-library Python helpers.
How do I stop the loop?
Create the `.autoresearch-off` file; Codex checks it between turns and during a turn. Removing the file does not reset the budget.
Discussion
No questions or reviews yet.
Related
SkillsA Codex skill that runs a loop of measurable experiments over a repository toward a numeric target: change, verify, revert failures, repeat
A Codex plugin for measured experiments in a repo: a baseline metric, tested small changes, and a patch with evidence
An autonomous iteration skill for agents: modify, verify, revert failed changes, and repeat the loop toward a target metric
A Claude Code skill that drives Codex over JSON-RPC: tasks, code reviews, parallel research and messaging between two agents.
A Claude Code skill that delegates tasks to OpenAI's Codex CLI for code analysis, review and edits
A Claude Code plugin: Claude does the task, then a stop hook starts an independent Codex review and Claude fixes the findings in the same session
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| autoresearch-claude-code (this card) | no | 350 | |
| Autoresearch for skills | no | 982 | a general autoresearch loop; this adds run limits, a Codex supervisor and state logging |
| Codex Autoresearch | no | 3,193 | a Codex variant; this card covers Claude Code and Codex through one protocol |
README in short
Installation uses symlinks, so the checkout must stay in place. Foreign files are never overwritten and conflicts are listed.