AI guru Karpathy previously created an autoresearch script that could run hundreds of tuning experiments overnight. The Autoresearch open-source project ports the same idea to Claude Code and Codex. Give it a goal and a quantitative metric, and the agent loops on its own—changing code, running verification, keeping changes that work, and auto-rolling back those that don’t. GitHub: http://github.com/uditgoenka/autoresearch … It provides 14 subcommands covering scenarios like tuning, bug hunting, security audit, and release, plus 9 built-in safety hooks to prevent misoperation. Just set a goal, leave it running, and check the results in the morning. Great for anyone who wants AI coding assistants to iterate automatically.

uditgoenka/autoresearch Source: https://github.com/uditgoenka/autoresearch

Autoresearch

Turn Claude Code (https://docs.anthropic.com/en/docs/claude-code), OpenCode (https://opencode.ai), or OpenAI Codex (https://developers.openai.com/codex) into a relentless improvement engine.

Based on Karpathy’s autoresearch (https://github.com/karpathy/autoresearch) — constraint + mechanical metric + autonomous iteration = compounding gains.

Claude Code Skill (https://docs.anthropic.com/en/docs/claude-code) OpenCode (https://opencode.ai) Codex (https://developers.openai.com/codex) Version (https://github.com/uditgoenka/autoresearch/releases) License: MIT

Based on (https://github.com/karpathy/autoresearch)

Follow @iuditg (https://x.com/intent/follow?screen_name=iuditg) Support (https://paypal.me/uditgoenka)

“Set the GOAL → The agent runs the LOOP → You wake up to results”

You don’t need AGI. You need a goal, a metric, and a loop that never quits.

Supports Claude Code, OpenCode, and OpenAI Codex. 14 commands. 9 safety hooks. 95% fewer tokens per invocation.

v2.2.0 — Autonomous Orchestrator: Type a plain-language goal to /autoresearch and it classifies your goal, derives a Success predicate, confirms it once, then loops across subcommands until done. No manual chaining required. Metric:/Verify: invocations run the classic loop unchanged. See guide/autoresearch-orchestrator.md.

How It Works · Commands · Quick Start · Guides · FAQ

`` PLAN LOOP DEBUG FIX SECURE SHIP ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Goal │ │ Modify │ │ Find │ │ Fix │ │ STRIDE │ │ Stage │ │ Metric │────▶│ Verify │────▶│ Bugs │────▶│ Errors │────▶│ OWASP │────▶│ Deploy │ │ Scope │ │Keep/Drop │ │ Trace │ │ Repair │ │ Red Team │ │ Release │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘

/autoresearch: /autoresearch /autoresearch: /autoresearch: /autoresearch: /autoresearch: plan debug fix security ship ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Probe │ │ Scenario │ │ Predict │ │ Reason │ │ Require- │ │ Edge │ │ 5-Expert │ │ Debate │ │ ments │ │ Cases │ │ Swarm │ │ Converge │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ /autoresearch: /autoresearch: /autoresearch: /autoresearch: probe scenario predict reason ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Learn │ │ Improve │ │ Eval │ │ Baseline │ │ Docs │ │ Research │ │ Analyze │ │ Diff │ │ Gen │ │ PRDs │ │ Results │ │ Verdict │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ /autoresearch: /autoresearch: /autoresearch: /autoresearch: learn improve evals regression ``

Why This Exists

Karpathy’s autoresearch (https://github.com/karpathy/autoresearch) demonstrated that a 630-line Python script could autonomously improve ML models overnight — 100 experiments per night — by following simple principles: one metric, constrained scope, fast verification, automatic rollback, git as memory.

Claude Autoresearch generalizes these principles to ANY domain. Not just ML — code, content, marketing, sales, HR, DevOps, or anything with a number you can measure.

v2.1.0 is a major architecture rebuild. The monolithic SKILL.md (813 lines, ~100K tokens per invocation) is replaced with a thin 41-line routing file and 12 self-contained command files (94–120 lines each, ~5–8K tokens per invocation). That is a 95% token reduction with the same capability surface.

How It Works

`` LOOP (N iterations or until done):

1. Review current state + git history + results log
2. Pick the next change (based on what worked, what failed, what’s untried)
3. Make ONE focused change
4. Git commit (before verification)
5. Run mechanical verification (tests, benchmarks, scores)
6. If improved → keep. If worse → git revert. If crashed → fix or skip.
7. Log the result
8. Repeat until N iterations complete or goal is met. ``

Every improvement stacks. Every failure auto-reverts. Progress is logged in TSV format.

The Setup Phase

Before looping, Claude performs a one-time setup:

1. Read context — reads all in-scope files
2. Define goal — extracts or asks for a mechanical metric
3. Define scope — which files can be modified vs read-only
4. Establish baseline — runs verification on current state (iteration #0)
5. Confirm and go — shows setup, then begins the loop

8 Critical Rules

Hooks & Safety

v2.1.1 ships a 9-hook safety system that protects your sessions automatically. Hooks fire on every session — not just during autoresearch commands.

What’s Protected

Configuration

All hooks are on by default. Disable individually:

``bash

Disable a specific hook

export AR_DISABLE_SCOUT_BLOCK=1 export AR_DISABLE_PRIVACY_BLOCK=1 export AR_DISABLE_DANGEROUS_CMD_BLOCK=1

… etc for each hook name

``

Optional webhook for session completion notifications:

bash export AR_NOTIFY_WEBHOOK=https://hooks.slack.com/services/...

Customize blocked directories with a .ckignore file (gitignore syntax) at your project root. See guide/hooks.md for full reference.

Commands

Universal flags: Iterations: N, Iterations: unlimited, --evals, --evals-interval N, --chain, -- shorthand.

All commands use interactive setup when invoked without arguments. Just type the command — the agent asks for what it needs with smart defaults based on your codebase.

OpenCode users: Commands use underscore naming (/autoresearch_debug, /autoresearch_fix, etc.). All 14 commands available.

Codex users: Invoke via $autoresearch mention syntax. Subcommands are keywords: $autoresearch debug, $autoresearch plan, etc.

Quick Decision Guide

Quick Start

Claude Code

Option A — npx install (recommended):

bash npx skills add uditgoenka/autoresearch

All 14 commands are available after restarting Claude Code.

Option B — Plugin install:

/plugin marketplace add uditgoenka/autoresearch /plugin install autoresearch@autoresearch

Note: Start a new Claude Code session after installing. Reference files aren’t resolvable in the same session where installation happened — this is a Claude Code platform limitation.

Updating (no reinstall needed):

/plugin update autoresearch

Run /reload-plugins to activate. No need to uninstall or re-clone.

Option C — Manual copy:

``bash git clone https://github.com/uditgoenka/autoresearch.git

Copy skill + subcommands to your project

cp -r autoresearch/.claude/skills/autoresearch .claude/skills/autoresearch cp -r autoresearch/.claude/commands/autoresearch .claude/commands/autoresearch cp autoresearch/.claude/commands/autoresearch.md .claude/commands/autoresearch.md ``

Or install globally:

bash cp -r autoresearch/.claude/skills/autoresearch ~/.claude/skills/autoresearch cp -r autoresearch/.claude/commands/autoresearch ~/.claude/commands/autoresearch cp autoresearch/.claude/commands/autoresearch.md ~/.claude/commands/autoresearch.md

Option D — Guided installer:

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

OpenCode Quick Start

Option A — Guided installer (recommended):

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

Option B — Manual copy:

bash git clone https://github.com/uditgoenka/autoresearch.git cp -r autoresearch/.opencode/skills/autoresearch .opencode/skills/autoresearch cp autoresearch/.opencode/commands/autoresearch*.md .opencode/commands/

Or globally:

bash cp -r autoresearch/.opencode/skills/autoresearch ~/.config/opencode/skills/autoresearch cp autoresearch/.opencode/commands/autoresearch*.md ~/.config/opencode/commands/

All 14 commands available as /autoresearch_debug, /autoresearch_fix, /autoresearch_improve, etc.

Codex Quick Start

Option A — Guided installer (recommended):

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

Option B — Manual copy:

bash git clone https://github.com/uditgoenka/autoresearch.git cp -r autoresearch/.agents/skills/autoresearch ~/.codex/skills/autoresearch

Invoke via $autoresearch mention syntax. Subcommands are keywords: $autoresearch plan, $autoresearch debug, $autoresearch evals, etc.

Run It

/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

Claude reads all files, establishes a baseline, and starts iterating — one change at a time. Keeps improvements, auto-reverts failures, logs everything. Stops after N iterations or when you interrupt.

/autoresearch:plan — Goal to Config

The hardest part isn’t the loop — it’s defining Scope, Metric, and Verify correctly. /autoresearch:plan converts your plain-language goal into a validated, ready-to-execute configuration.

/autoresearch:plan Goal: Make the API respond faster

Walks through 5 steps: capture goal → define scope → define metric → define direction → validate verify command (dry-run). Every gate is mechanical — scope must resolve to files, metric must output a number, verify must pass a dry-run. Emits a handoff.json for chaining.

/autoresearch:debug — Autonomous Bug Hunter

Scientific method meets autoresearch loop. Doesn’t stop at one bug — iteratively hunts ALL bugs using falsifiable hypotheses, evidence-based investigation, and 7 investigation techniques.

/autoresearch:debug Scope: src/api/**/*.ts Symptom: API returns 500 on POST /users Iterations: 15

How it works: Gather symptoms → Recon → Hypothesize (specific, testable) → Test (one experiment per iteration) → Classify (confirmed/disproven/inconclusive) → Log → Repeat. Every finding requires code evidence (file:line + reproduction steps). Every disproven hypothesis is logged — equally valuable.

/autoresearch:fix — Autonomous Error Crusher

Takes a broken state and iteratively repairs it until everything passes. ONE fix per iteration. Atomic, committed, verified, auto-reverted on failure.

/autoresearch:fix Iterations: 20

Auto-detects what’s broken (tests, types, lint, build) → Prioritizes (blockers first) → Fixes ONE thing → Commits → Verifies error count decreased