Claude Autoresearch

Turn Claude Code into a relentless improvement engine.

Based on Karpathy's autoresearch — constraint + mechanical metric + autonomous iteration = compounding gains.

imageClaude Code Skill imageVersion imageLicense: MIT imageBased on imageFollow @iuditg

"Set the GOAL → Claude 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.

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

Why This Exists

Karpathy's 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.

How It Works

LOOP (FOREVER or N times):
  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. Never stop until you interrupt (or N iterations complete).

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

Commands

Quick Decision Guide

Quick Start

1. Install

Option A — Plugin install (recommended):

Step 1: Register the autoresearch marketplace (one-time). Add this entry to ~/.claude/plugins/known_marketplaces.json:

{
  "autoresearch": {
    "source": { "source": "github", "repo": "uditgoenka/autoresearch" },
    "installLocation": "<HOME>/.claude/plugins/marketplaces/autoresearch",
    "lastUpdated": "2026-03-16T00:00:00.000Z"
  }
}

Replace <HOME> with your home directory path (e.g., /Users/yourname on macOS, C:\\Users\\yourname on Windows, /home/yourname on Linux). If the file already has entries, add "autoresearch": { ... } as a new key alongside the existing ones.

Step 2: Restart Claude Code, then run:

/plugin install autoresearch@autoresearch

That's it. All 6 commands are available immediately.

Option B — Manual copy:

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

# Copy skill + subcommands to your project
cp -r autoresearch/skills/autoresearch .claude/skills/autoresearch
cp -r autoresearch/commands/autoresearch .claude/commands/autoresearch

Or install globally:

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

Note: The commands/ directory is required for subcommands (/autoresearch:ship, /autoresearch:plan, /autoresearch:security) to work.

2. 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"

3. Walk Away

Claude reads all files, establishes a baseline, and starts iterating — one change at a time. Keep improvements, auto-revert failures, log everything. Never stops until you interrupt (or N iterations complete).

/autoresearch:plan — Goal → Config Wizard

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

The wizard walks you 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.

/autoresearch:security — Autonomous Security Audit

Read-only security audit using STRIDE threat modeling, OWASP Top 10 sweeps, and red-team adversarial analysis with 4 hostile personas.

/loop 10 /autoresearch:security

What it does: Codebase recon → asset inventory → trust boundaries → STRIDE threat model → attack surface map → autonomous testing loop → structured report.

Every finding requires code evidence (file:line + attack scenario). No theoretical fluff.

Output: Creates security/{date}-{slug}/ with 7 structured report files.

/autoresearch:ship — Universal Shipping Workflow

Ship anything through 8 phases: Identify → Inventory → Checklist → Prepare → Dry-run → Ship → Verify → Log.

/autoresearch:ship --auto

Auto-detects what you're shipping (code PR, deployment, blog post, email campaign, sales deck, research paper, design assets) and generates domain-specific checklists — every item mechanically verifiable.

9 supported types: code-pr, code-release, deployment, content, marketing-email, marketing-campaign, sales, research, design.

/autoresearch:debug — Autonomous Bug Hunter (v1.3.0)

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.

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

How it works: Gather symptoms → Recon (map error surface) → 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. Uses 7 techniques: binary search, differential debugging, minimal reproduction, trace execution, pattern search, working backwards, rubber duck.

/autoresearch:fix — Autonomous Error Crusher (v1.3.0)

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

/autoresearch:fix

How it works: Auto-detects what's broken (tests, types, lint, build) → Prioritizes (blockers first) → Fixes ONE thing → Commits → Verifies error count decreased → Guard check (no regressions) → Keep/Revert → Repeat until zero errors.

Stops automatically when error count hits zero — even in unbounded mode.

Chain them: /loop 15 /autoresearch:debug then /loop 30 /autoresearch:fix --from-debug

Guard — Prevent Regressions (v1.0.4)

When optimizing a metric, the loop might break existing behavior. Guard is an optional safety net.

/autoresearch
Goal: Reduce API response time to under 100ms
Verify: npm run bench:api | grep "p95"
Guard: npm test

• Verify = "Did the metric improve?" (the goal)
• Guard = "Did anything else break?" (the safety net)

If the metric improves but the guard fails, Claude reworks the optimization (up to 2 attempts). Guard/test files are never modified.

Credit: Guard was contributed by @pronskiy (JetBrains) in PR #7.

Results Tracking

Every iteration is logged in TSV format:

iteration  commit   metric  delta   status    description
0          a1b2c3d  85.2    0.0     baseline  initial state
1          b2c3d4e  87.1    +1.9    keep      add tests for auth edge cases
2          -        86.5    -0.6    discard   refactor test helpers (broke 2 tests)
3          c3d4e5f  88.3    +1.2    keep      add error handling tests

Every 10 iterations, Claude prints a progress summary. Bounded loops print a final summary with baseline → current best.

Crash Recovery

Repository Structure

autoresearch/
├── README.md
├── EXAMPLES.md                                    ← Real-world examples by domain
├── LICENSE
├── .claude-plugin/
│   ├── marketplace.json                           ← Plugin marketplace manifest
│   └── plugin.json                                ← Plugin metadata
├── commands/
│   └── autoresearch/
│       ├── ship.md                                ← /autoresearch:ship registration
│       ├── plan.md                                ← /autoresearch:plan registration
│       ├── security.md                            ← /autoresearch:security registration
│       ├── debug.md                               ← /autoresearch:debug registration
│       └── fix.md                                 ← /autoresearch:fix registration
└── skills/
    └── autoresearch/
        ├── SKILL.md                               ← Main skill (loaded by Claude Code)
        └── references/
            ├── autonomous-loop-protocol.md        ← 8-phase loop protocol
            ├── core-principles.md                 ← 7 universal principles
            ├── plan-workflow.md                   ← Plan wizard protocol
            ├── security-workflow.md               ← Security audit protocol
            ├── ship-workflow.md                   ← Ship workflow protocol
            ├── debug-workflow.md                  ← Debug loop protocol
            ├── fix-workflow.md                    ← Fix loop protocol
            └── results-logging.md                 ← TSV tracking format

FAQ

Q: I don't know what metric to use. A: Run /autoresearch:plan — it analyzes your codebase, suggests metrics, and dry-runs the verify command before you launch.

Q: Does this work with any project? A: Yes. Any language, framework, or domain. Copy the skill to .claude/skills/autoresearch/ and the commands to .claude/commands/autoresearch/.

Q: How do I stop the loop? A: Ctrl+C or use /loop N /autoresearch to run exactly N iterations. Claude commits before verifying, so your last successful state is always in git.

Q: Can I use this for non-code tasks? A: Absolutely. Sales emails, marketing copy, HR policies, runbooks — anything with a measurable metric. See EXAMPLES.md.

Q: Does /autoresearch:security modify my code? A: No. It's read-only — analyzes code and produces a structured report. Use --fix to opt into auto-remediation of confirmed Critical/High findings.

Q: Can I use MCP servers? A: Yes. Any MCP server configured in Claude Code is available during the loop for database queries, API calls, analytics, etc. See EXAMPLES.md.

Contributing

Contributions welcome! See CONTRIBUTING.md.

Areas of interest: new domain examples, verification script templates, CI/CD integrations, real-world benchmarks.

Star History

License

MIT — see LICENSE.

Credits

• Andrej Karpathy — for autoresearch
• Anthropic — for Claude Code and the skills system

About the Author

Udit Goenka — AI Product Expert, Founder & Angel Investor

Self-taught builder who went from a slow internet connection in India to founding multiple companies and helping 700+ startups generate over ~$25m in revenue.

Building: TinyCheque (India's first agentic AI venture studio) · Firstsales.io (sales automation)

Investing: 38 startups backed, 6 exits. Focused on early-stage AI and SaaS.

Connect: udit.co · @iuditg · @uditgoenka · Newsletter

"Autonomy scales when you constrain scope, clarify success, mechanize verification, and let agents optimize tactics while humans optimize strategy."