autoimprove

Autonomous code improvement engine. Define quality assertions, let the machine hill-climb toward perfection.

Inspired by Karpathy's autoresearch.

How it works

  ┌─ OPTIMIZE ──┐    ┌─ GENERATE ──┐
  │ claude -p    │───▶│ run command  │
  │ edits code   │    │ build output │
  └──────────────┘    └──────┬───────┘
                             │
  ┌─ DECIDE ────┐    ┌─ EVALUATE ──┐
  │ improved?    │◀───│ assertions   │
  │ Y: commit    │    │ on output    │
  │ N: revert    │    │ → score      │
  └──────┬───────┘    └─────────────┘
         │
  score >= target? → STOP
  plateau? → STOP
  else → next iteration

Each iteration:

1. Optimize — Claude edits your code to fix failing assertions
2. Generate — Run your build/generate command
3. Evaluate — Anthropic API checks all assertions (visual or text)
4. Decide — Improvement? Commit. Regression? Revert.

Fresh context per iteration via claude -p. Can run 100+ iterations without degradation.

Install

Open Claude Code and paste this. Claude will do the rest.

Install autoimprove: run git clone https://github.com/xto42/autoimprove.git ~/.claude/skills/autoimprove && cd ~/.claude/skills/autoimprove && ./setup then add an "autoimprove" section to CLAUDE.md that describes the available skill: /autoimprove — autonomous code improvement engine that iteratively optimizes code to pass quality assertions. Available commands: /autoimprove (interactive setup), /autoimprove run <task> (run existing task), /autoimprove status (check results), /autoimprove dry-run <task> (verify setup).

For development:

git clone https://github.com/xto42/autoimprove.git
cd autoimprove && ./setup

Usage

As a Claude Code skill:

/autoimprove              # Interactive setup
/autoimprove run my-task  # Run an existing task
/autoimprove status       # Check last run results

As a standalone CLI:

bun run engine/src/cli.ts --task my-task
bun run engine/src/cli.ts --task my-task --resume
bun run engine/src/cli.ts --task my-task --dry-run
bun run engine/src/cli.ts --version

Task config

Create .autoimprove/tasks/<name>.json:

{
  "name": "my-task",
  "description": "Improve the JSON output format",
  "evalMode": "text",
  "mutableFiles": ["src/generator.ts"],
  "readOnlyContext": ["src/types.ts"],
  "generate": {
    "command": "npx tsx scripts/generate.ts",
    "outputFile": "output.json"
  },
  "assertions": [
    { "id": "valid-json", "description": "Output is valid JSON" },
    { "id": "has-name", "description": "Output contains a 'name' field" }
  ],
  "assertionPacks": ["api-response"],
  "strategy": "Fix the JSON generator to produce valid, complete output",
  "targetScore": 0.95,
  "maxIterations": 100,
  "plateauThreshold": 5
}

Model routing

Role	Model	When
Evaluate	Haiku	Every iteration (fast + cheap)
Optimize	Sonnet	Default optimizer
Optimize	Opus	Plateau escalation (then back to Sonnet)

Assertion packs

Built-in packs in assertions/:

• web-quality — responsive, images, text overflow, accessibility
• document-quality — tables, alignment, fonts, page breaks
• api-response — JSON validity, types, naming, sensitive data
• code-quality — TODOs, console.log, types, dead code

Use packs via "assertionPacks": ["web-quality"] in your task config.

Terminal output

autoimprove v0.1.0
────────────────────────────────────
Task:       my-task
Mode:       text
Files:      src/generator.ts
Assertions: 10
Target:     95%
────────────────────────────────────

  ✓  #  1   50% █████████░░░░░░░░░░░ 5/10   sonnet
  ✗  #  2   50% █████████░░░░░░░░░░░ 5/10   sonnet
  ✓  #  3   70% █████████████░░░░░░░ 7/10   sonnet
  ✓  #  4  100% ████████████████████ 10/10  sonnet

────────────────────────────────────
Run complete
Status:     completed (Target score reached)
Best score: 100% (iteration #4)
────────────────────────────────────

Architecture

See ARCHITECTURE.md for design decisions.

License

MIT