Autoresearch

Autonomous experiment loop: try ideas, keep what works, discard what doesn't, never stop.

Tools

• init_experiment, configure session (name, metric, unit, direction). Call again to re-initialize with a new baseline when the optimization target changes.
• run_experiment, runs command, times it, captures output.
• log_experiment, records result. keep auto-commits. discard/crash/checks_failed auto-reverts code changes (autoresearch files preserved). Always include secondary metrics dict. Dashboard: ctrl+shift+t.

Session files

All session files live in a single .auto/ subfolder at the working directory root. This keeps everything in one place, easy to preserve across reverts, gitignore, and clean up.

File	Purpose
.auto/prompt.md	Experiment prompt / playbook (heart of the session)
.auto/measure.sh	Benchmark script, emits METRIC name=value lines
.auto/log.jsonl	Append-only result log (written by the tools)
.auto/ideas.md	Ideas backlog (optional)
.auto/checks.sh	Correctness checks (optional)
.auto/config.json	Session config (optional)
.auto/hooks/{before,after}.sh	Lifecycle hooks (optional)

Always create files in the .auto/ layout. Legacy flat autoresearch.* files are still read for in-flight sessions, but new sessions should use .auto/.

Setup

1. Ask (or infer): Goal, Command, Metric (+ direction), Files in scope, Constraints.
2. git checkout -b autoresearch/<goal>-<date>
3. Read the source files. Understand the workload deeply before writing anything.
4. mkdir -p .auto, then write .auto/prompt.md and .auto/measure.sh (see below). Commit both.
5. init_experiment → run baseline → log_experiment → start looping immediately.

.auto/prompt.md