Claude Autoresearch — Autonomous Goal-directed Iteration

Subcommands

/autoresearch

/autoresearch:plan

/autoresearch:plan — Goal → Configuration Wizard

references/plan-workflow.md

1. Capture Goal — ask what the user wants to improve (or accept inline text)
2. Analyze Context — scan codebase for tooling, test runners, build scripts
3. Define Scope — suggest file globs, validate they resolve to real files
4. Define Metric — suggest mechanical metrics, validate they output a number
5. Define Direction — higher or lower is better
6. Define Verify — construct the shell command, dry-run it, confirm it works
7. Confirm & Launch — present the complete config, offer to launch immediately

• Metric MUST be mechanical (outputs a parseable number, not subjective)
• Verify command MUST pass a dry run on the current codebase before accepting
• Scope MUST resolve to ≥1 file

/autoresearch:plan
Goal: Make the API respond faster

/autoresearch:plan Increase test coverage to 95%

/autoresearch:plan Reduce bundle size below 200KB

/autoresearch

When to Activate

• User invokes

  /autoresearch

  or

  /ug:autoresearch

  → run the loop
• User invokes

  /autoresearch:plan

  → run the planning wizard
• User says "help me set up autoresearch", "plan an autoresearch run" → run the planning wizard
• User says "work autonomously", "iterate until done", "keep improving", "run overnight" → run the loop
• Any task requiring repeated iteration cycles with measurable outcomes → run the loop

Optional: Controlled Loop Count

/loop

Requires: Claude Code v1.0.32+ (the

/loop

command was introduced in this version)

Usage

/autoresearch
Goal: Increase test coverage to 90%

/loop 25 /autoresearch
Goal: Increase test coverage to 90%

/autoresearch

/loop 25

When to Use Bounded Loops

/loop 10 /autoresearch

/loop 5 /autoresearch

/loop 15 /autoresearch

/loop N /autoresearch

Behavior with Loop Count

• Claude runs exactly N iterations through the autoresearch loop
• After iteration N, Claude prints a final summary with baseline → current best, keeps/discards/crashes
• If the goal is achieved before N iterations, Claude prints early completion and stops
• All other rules (atomic changes, mechanical verification, auto-rollback) still apply

Setup Phase (Do Once)

1. Read all in-scope files for full context before any modification
2. Define the goal — What does "better" mean? Extract or ask for a mechanical metric:
   • Code: tests pass, build succeeds, performance benchmark improves
   • Content: word count target hit, SEO score improves, readability score
   • Design: lighthouse score, accessibility audit passes
   • If no metric exists → define one with user, or use simplest proxy (e.g. "compiles without errors")
3. Define scope constraints — Which files can you modify? Which are read-only?
4. Create a results log — Track every iteration (see

   references/results-logging.md

   )
5. Establish baseline — Run verification on current state. Record as iteration #0
6. Confirm and go — Show user the setup, get confirmation, then BEGIN THE LOOP

The Loop

references/autonomous-loop-protocol.md

LOOP (FOREVER or N times):
  1. Review: Read current state + git history + results log
  2. Ideate: Pick next change based on goal, past results, what hasn't been tried
  3. Modify: Make ONE focused change to in-scope files
  4. Commit: Git commit the change (before verification)
  5. Verify: Run the mechanical metric (tests, build, benchmark, etc.)
  6. Decide:
     - IMPROVED → Keep commit, log "keep", advance
     - SAME/WORSE → Git revert, log "discard"
     - CRASHED → Try to fix (max 3 attempts), else log "crash" and move on
  7. Log: Record result in results log
  8. Repeat: Go to step 1.
     - If unbounded: NEVER STOP. NEVER ASK "should I continue?"
     - If bounded (N): Stop after N iterations, print final summary

Critical Rules

1. Loop until done — Unbounded: loop until interrupted. Bounded: loop N times then summarize.
2. Read before write — Always understand full context before modifying
3. One change per iteration — Atomic changes. If it breaks, you know exactly why
4. Mechanical verification only — No subjective "looks good". Use metrics
5. Automatic rollback — Failed changes revert instantly. No debates
6. Simplicity wins — Equal results + less code = KEEP. Tiny improvement + ugly complexity = DISCARD
7. Git is memory — Every kept change committed. Agent reads history to learn patterns
8. When stuck, think harder — Re-read files, re-read goal, combine near-misses, try radical changes. Don't ask for help unless truly blocked by missing access/permissions

Principles Reference

references/core-principles.md

Adapting to Different Domains

src/**/*.ts

npm test

src/components/**

npx lighthouse

train.py

uv run train.py

content/*.md

npm run bench

npm test && wc -l