Autoresearch: Autonomous Iteration for LLM-Powered Code Improvement

Introduction

The uditgoenka/autoresearch repository introduces a groundbreaking skill for AI agents, particularly those powered by Claude Code, OpenCode, and OpenAI Codex. This project takes inspiration from Andrej Karpathy's original autoresearch concept, which demonstrated how a simple script could autonomously enhance machine learning models. Autoresearch generalizes this principle, turning any LLM into a "relentless improvement engine" capable of autonomous, goal-directed iteration. It operates on a core loop: modify, verify, keep/discard, and repeat, allowing for continuous, compounding gains in various tasks, not just limited to machine learning.

Installation

Getting started with Autoresearch is straightforward, with options tailored for different platforms:

For Claude Code (Recommended via npx):
```
npx skills add uditgoenka/autoresearch
```
After installation, restart Claude Code to access all 14 commands.

For OpenCode (Recommended via Guided Installer):

git clone https://github.com/uditgoenka/autoresearch.git
cd autoresearch
./scripts/install.sh --opencode --global

OpenCode commands use underscore naming, e.g., /autoresearch_debug.

For OpenAI Codex (Recommended via Guided Installer):
```
git clone https://github.com/uditgoenka/autoresearch.git
cd autoresearch
./scripts/install.sh --codex --global
```
Codex commands are invoked using mention syntax, e.g., $autoresearch debug.

Detailed instructions and alternative manual installation methods are available in the official repository's README.

Examples

Autoresearch offers a comprehensive suite of commands designed to automate various development and operational tasks. Here are a few highlights:

/autoresearch (Core Loop / Orchestrator): The central command. In its classic mode, you define a goal, metric, and verification step, and it iteratively modifies code to improve the metric. The new autonomous orchestrator mode allows you to simply state a plain-language goal, and it intelligently selects and chains subcommands until the goal is met.
```
/autoresearch
Goal: Increase test coverage from 72% to 90%
Scope: src/**/*.test.ts, src/**/*.ts
Metric: coverage % (higher is better)
Verify: npm test -- --coverage | grep "All files"
Iterations: 25
```
Or, using the orchestrator:
```
/autoresearch fix the login bug
```
/autoresearch:plan: Helps define the crucial Goal, Scope, Metric, and Verify steps by converting a plain-language goal into a validated configuration.
```
/autoresearch:plan
Goal: Make the API respond faster
```
/autoresearch:debug: An autonomous bug hunter that iteratively finds and classifies bugs using falsifiable hypotheses. It can be chained with /autoresearch:fix.
```
/autoresearch:debug
Scope: src/api/**/*.ts
Symptom: API returns 500 on POST /users
Iterations: 15
```
/autoresearch:fix: Designed to crush errors one-by-one, automatically detecting and prioritizing broken tests, types, or linting issues until the error count hits zero.
```
/autoresearch:fix
Iterations: 20
```
/autoresearch:security: Performs a read-only security audit using STRIDE threat modeling, OWASP Top 10 sweeps, and red-team adversarial analysis.
```
/autoresearch:security
Iterations: 15
```
/autoresearch:ship: A universal shipping workflow that guides any release (code, deployment, content) through 8 phases, with mechanically verifiable checklists.
```
/autoresearch:ship --auto
```

The project emphasizes "8 Critical Rules" for effective autonomous iteration, including bounded iterations, read-before-write, one change per iteration, mechanical verification, automatic rollback, and using Git as memory.

Why Use It

Autoresearch stands out by providing a robust framework for leveraging LLMs to achieve continuous, measurable improvements. Its key advantages include:

Autonomous Improvement: It automates the tedious cycle of modifying, testing, and refining, allowing agents to work tirelessly towards a defined goal.
Versatility: Applicable across virtually any domain, from code optimization and bug fixing to security audits, documentation generation, and even product research, as long as a measurable metric or verifiable predicate can be established.
Efficiency: The v2.1.0 architecture rebuild significantly reduced token usage, making operations more cost-effective and faster.
Safety and Reliability: Features like automatic rollback, bounded iterations, and comprehensive hooks (e.g., privacy-block, dangerous-cmd-block) ensure that autonomous changes are controlled and safe.
Structured Workflow: It provides a clear, rule-based approach to problem-solving, ensuring that progress is systematic and traceable through detailed TSV logs and Git commits.