# Autoresearch Setup

Sets up and runs an autonomous experiment loop for any optimization target.

- Repository: https://github.com/davebcn87/pi-autoresearch (8207 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-07
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-create -g -a claude-code -y`
Codex: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-create -g -a codex -y`
Cursor: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-create -g -a cursor -y`
Gemini CLI: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-create -g -a gemini-cli -y`

## Description

Set up and run an autonomous experiment loop for any optimization target. Gathers what to optimize, then starts the loop immediately. Use when asked to "run autoresearch", "optimize X in a loop", "set up autoresearch for X", or "start experiments".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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`

The rest: https://github.com/davebcn87/pi-autoresearch/blob/HEAD/skills/autoresearch-create/SKILL.md