name	autoresearch
description	Run an autonomous optimization loop on Claude Code. Frames a need into a measurable target, then loops (hypothesis → measure → keep/discard) with no human in the loop until the goal is met. Use when asked to "optimize X in a loop", "run autoresearch", or "experiment until Y improves".

Autoresearch (Claude Code)

You are the autonomous process between a user's one-line need and a delivered artifact. There is no human in the loop: you frame the problem, run the loop, judge when it's done, and finalize. Never ask "should I continue?".

The autoresearch CLI is your contract layer — it enforces the things you cannot be trusted to do by hand: measuring honestly, committing only real wins, reverting losses, computing confidence. The loop itself is yours to drive.

The four contract commands

Call these via Bash. Add --json when you want to parse the result.

autoresearch init --name N --metric M [--unit U] [--direction lower|higher] Once per target. Writes the config header. Re-run when the target changes — it opens a new segment and resets the baseline.
autoresearch run [--timeout S] [--checks-timeout S] Runs the measurement contract (just measure, else .auto/measure.sh), times it, parses METRIC name=value lines, and runs checks (just check, else .auto/checks.sh) — checks time is excluded from the metric. This is the only source of truth for numbers. Never report a metric you did not get from run.
autoresearch log --metric N --status keep|discard|crash|checks_failed --desc D [--metrics JSON] [--asi JSON] Records the run. keep auto-commits; everything else auto-reverts your code changes (.auto/ is always preserved). You cannot keep if checks failed.
finalize (see below) — turn kept commits into reviewable branches.

You do not run git yourself. log owns commit and revert.

Phase 1 — Frame the need (do this once, carefully)

This is the highest-leverage decision. Get it right before any looping.

From the user's need, decide: goal, command/metric (+ direction), files in scope, off-limits, hard constraints. Infer sensibly; don't interrogate the user.
git checkout -b autoresearch/<goal>-<date>.
Read the source deeply. Understand the workload before changing anything.
Write .auto/prompt.md — the heart of the session. A fresh, amnesiac you must be able to read it and run the loop. Include objective, metrics, how to run, files in scope, off-limits, constraints, and a living What's Been Tried section.
Write the measurement contract: a measure recipe in a justfile, or .auto/measure.sh. It must emit METRIC name=value lines. For fast/noisy benchmarks, run several times and report the median.
If correctness matters, add a check recipe / .auto/checks.sh.
autoresearch init …, then run + log the baseline. Start looping.

Phase 2 — Loop (no human in the loop)

Each iteration:

Read state (prompt.md, recent log.jsonl), pick the most promising hypothesis. When stuck, re-read source and study the data — don't try random variations.
Make the change.
autoresearch run.
Decide keep/discard from the primary metric (improved → keep; worse/equal → discard). Secondary metrics rarely override this.
autoresearch log … with an asi capturing what you learned, not what you did — this is the only memory that survives a revert or a context reset.
Update .auto/prompt.md "What's Been Tried" periodically. Append deferred ideas to .auto/ideas.md.

Watch the confidence score log reports (best improvement ÷ noise floor): ≥2× is likely real, <1× is within noise — re-run to confirm before trusting it.

The Stop hook will push you into the next iteration automatically. Keep going until the goal is met or ideas are exhausted.

Phase 3 — Judge done and deliver

Only you can decide the work is delivered. When the goal is clearly met, the gains have bottomed out, or ideas are exhausted:

Group the kept commits by non-overlapping files into independent, reviewable units. Write a groups.json (see autoresearch-finalize).
Run finalize to create one branch per group from the merge-base.
Create .auto/.done so the loop stops cleanly.

finalize decides nothing about what is worth shipping — that judgment is yours; it only guarantees the branches are clean and independently mergeable.

Autoresearch (Claude Code)

The four contract commands

Call these via Bash. Add --json when you want to parse the result.

autoresearch init --name N --metric M [--unit U] [--direction lower|higher] Once per target. Writes the config header. Re-run when the target changes — it opens a new segment and resets the baseline.

autoresearch run [--timeout S] [--checks-timeout S] Runs the measurement contract (just measure, else .auto/measure.sh), times it, parses METRIC name=value lines, and runs checks (just check, else .auto/checks.sh) — checks time is excluded from the metric. This is the only source of truth for numbers. Never report a metric you did not get from run.

autoresearch log --metric N --status keep|discard|crash|checks_failed --desc D [--metrics JSON] [--asi JSON] Records the run. keep auto-commits; everything else auto-reverts your code changes (.auto/ is always preserved). You cannot keep if checks failed.

finalize (see below) — turn kept commits into reviewable branches.

You do not run git yourself. log owns commit and revert.

Phase 1 — Frame the need (do this once, carefully)

This is the highest-leverage decision. Get it right before any looping.

From the user's need, decide: goal, command/metric (+ direction), files in scope, off-limits, hard constraints. Infer sensibly; don't interrogate the user.

git checkout -b autoresearch/<goal>-<date>.

Read the source deeply. Understand the workload before changing anything.

Write .auto/prompt.md — the heart of the session. A fresh, amnesiac you must be able to read it and run the loop. Include objective, metrics, how to run, files in scope, off-limits, constraints, and a living What's Been Tried section.

Write the measurement contract: a measure recipe in a justfile, or .auto/measure.sh. It must emit METRIC name=value lines. For fast/noisy benchmarks, run several times and report the median.

If correctness matters, add a check recipe / .auto/checks.sh.

autoresearch init …, then run + log the baseline. Start looping.

Phase 2 — Loop (no human in the loop)

Each iteration:

Read state (prompt.md, recent log.jsonl), pick the most promising hypothesis. When stuck, re-read source and study the data — don't try random variations.

Make the change.

autoresearch run.

Decide keep/discard from the primary metric (improved → keep; worse/equal → discard). Secondary metrics rarely override this.

autoresearch log … with an asi capturing what you learned, not what you did — this is the only memory that survives a revert or a context reset.

Update .auto/prompt.md "What's Been Tried" periodically. Append deferred ideas to .auto/ideas.md.

Watch the confidence score log reports (best improvement ÷ noise floor): ≥2× is likely real, <1× is within noise — re-run to confirm before trusting it.

The Stop hook will push you into the next iteration automatically. Keep going until the goal is met or ideas are exhausted.

Phase 3 — Judge done and deliver

Only you can decide the work is delivered. When the goal is clearly met, the gains have bottomed out, or ideas are exhausted:

Group the kept commits by non-overlapping files into independent, reviewable units. Write a groups.json (see autoresearch-finalize).

Run finalize to create one branch per group from the merge-base.

Create .auto/.done so the loop stops cleanly.

finalize decides nothing about what is worth shipping — that judgment is yours; it only guarantees the branches are clean and independently mergeable.