# Autoresearch — Autonomous Goal-Directed Iteration for Claude Code

> Open-source Claude Code skill inspired by Karpathy's autoresearch. Modify, verify, keep/discard, repeat — autonomously. Works on any task with a measurable metric.

## How It Works

1. Define your goal and a mechanical metric (test coverage, build time, lighthouse score, etc.)
2. Claude loops autonomously — one atomic change per iteration, commit before verify, auto-revert on failure
3. Every iteration is logged. Kept changes stay as git commits. You get a clean history of what worked.

## Key Features

- **Constraint-Driven Loop**: One change per iteration. Commit before verify. Auto-revert on failure.
- **Mechanical Verification**: No subjective "looks good." Every iteration runs a real metric.
- **Automatic Rollback**: Failed changes revert instantly via git reset.
- **Git as Memory**: Agent reads its own git history to learn what works.
- **Results Logging**: TSV log tracks every iteration — metric, delta, status, description.
- **Domain-Agnostic**: Works on backend code, ML training, frontend UI, content, performance.

## Use Cases

| Domain | Metric | Verify Command |
|--------|--------|----------------|
| Backend Code | Tests pass + coverage % | npm test |
| Frontend UI | Lighthouse score | npx lighthouse |
| ML Training | val_bpb / loss | uv run train.py |
| Performance | Benchmark time (ms) | npm run bench |
| Refactoring | Tests pass + LOC reduced | npm test && wc -l |

## Quick Start

```bash
# Install
git clone https://github.com/uditgoenka/autoresearch.git /tmp/autoresearch
cp -r /tmp/autoresearch/skills/autoresearch ~/.claude/skills/autoresearch

# Run unlimited
/autoresearch

# Run bounded (25 iterations)
/loop 25 /autoresearch
```

## FAQ

**What is autoresearch?**
A Claude Code skill that applies Karpathy's autoresearch principles to any task.

**Does it only work for ML research?**
No. Any task with a measurable outcome works.

**Can I limit the number of iterations?**
Yes. Use /loop N /autoresearch (requires Claude Code v1.0.32+).

**Is it safe to run overnight?**
Yes. Every change is committed before verification, so rollback is always clean.

## Links

- Source: [github.com/uditgoenka/autoresearch](https://github.com/uditgoenka/autoresearch)
- Page: https://udit.co/projects/autoresearch