🔬 Autoresearch Skill

Autonomous, Goal-Directed Iteration for Claude Code

Inspired by Andrej Karpathy's autoresearch — extended into a universal, real-data benchmark-driven workflow for any engineering task.

          ╔════════════════════════════════════════════════════╗
          ║   MODIFY → VERIFY → REGRESS → KEEP / DISCARD → ∞   ║
          ╚════════════════════════════════════════════════════╝

---

✨ What is this?

Autoresearch is a Claude Code skill that turns a free-form goal like

/autoresearch reduce API p95 latency to 200ms

into an autonomous, self-correcting optimization loop that:

1. 🧠 Parses the goal into seven machine-readable slots
2. 📦 Ingests real data (refusing synthetic corpora)
3. 🛠️ Builds a single-file benchmark harness
4. 📐 Captures a baseline + regression test count
5. 🔁 Iterates — one atomic change at a time
6. ✅ Keeps wins, 🗑️ auto-discards regressions, logs everything
7. 🏁 Stops when the target metric is hit

No hand-holding. No "should I continue?" Just mechanical iteration until the goal is reached.

---

🌟 Why use it?

🎯 Mechanical, not subjective

Every iteration is judged by a single floating-point metric extracted from a command. "Looks better" is banned.

🛡️ Regression-proof

A hard gate rolls back any change that drops a pre-existing passing test — no matter how big the win looked.

📊 Real data only

The harness refuses synthetic corpora. If you can't scrape, export, or tail it from reality, the loop won't start.

♻️ Atomic & reversible

One change per iteration, git-committed before verification. A failed experiment is always git reset --hard HEAD~1 away.

🧩 Domain-agnostic

Backend latency, test coverage, bundle size, flakiness, LOC, build time, lighthouse scores — same loop, different metric.

🌐 Global Claude Code skill

Install once under ~/.claude/skills/autoresearch/ and invoke /autoresearch <goal> from any project.

---

🚀 Quick Start

1. Install (global skill)

# Clone into your Claude Code skills directory
git clone https://github.com/Muminur/autoresearch-skill-Andrej-Karpathy.git \
  ~/.claude/skills/autoresearch

On Windows:

git clone https://github.com/Muminur/autoresearch-skill-Andrej-Karpathy.git `
  "$env:USERPROFILE\.claude\skills\autoresearch"

2. Invoke

Open Claude Code in any project and type:

/autoresearch reduce avg_latency_ms below 500

Claude will print the parsed slot dump, walk through the five harness phases, then begin the autonomous loop.

3. Watch it work

Results are appended to autoresearch/results.tsv in your project:

commit    metric     avg_latency_ms  status      description
953b71d   1.000000   2008.9          baseline    77-case corpus, 10 signals executed
953b71d   1.000000   646.4           keep        parallelize _place_exits with asyncio.gather
953b71d   1.000000   592.1           keep        add 30s TTL cache on account()
953b71d   1.000000   488.8           keep        prewarm account+connection pool, serialize signals

---

🔌 Use with other AI coding assistants