autoresearch

autoresearch puts Claude Code in an autonomous experiment loop. Claude tries an idea, benchmarks it, keeps the change with a git commit if the number improves, reverts it if not, and moves on to the next idea without waiting for you. It is bn-l’s port of pi-autoresearch 1.8.1, by Tobi Lutke and David Cortés, from the pi coding agent to Claude Code. It keeps pi-autoresearch’s session format, .auto/log.jsonl, so a session can move between the two.

What it does

• Three tools. While the mode is on, Claude gets init_experiment (session name, metric, unit, and whether lower or higher is better), run_experiment (runs a benchmark command with a 600-second default timeout, then .auto/checks.sh if it exists) and log_experiment (records the run as keep, discard, crash or checks_failed, with optional secondary metrics).
• Keep or revert. A kept run is committed, anything else is rolled back, and a run whose checks failed cannot be kept. Each logged run updates a confidence score: the best improvement as a multiple of the noise between runs.
• Display. A band above the prompt sums up the session, and the tool rows show a running benchmark’s live output. /autoresearch dashboard opens a full-screen pane with every run (j/k, u/d, g, End, q). /autoresearch web opens a live dashboard in your browser.
• Waits instead of failing. If Claude ends a turn by asking you something, the loop waits five minutes for your reply, then carries on. If a usage limit is hit, it waits for the reset. A status line under the prompt says which.
• Your changes first. Before starting over uncommitted changes, it lists them and asks whether to stash them, start anyway, or not start. Changes it stashed are offered back when the loop stops.
• Scripts of your own. Executable .auto/hooks/before.sh and after.sh run around each iteration with the session as JSON on stdin, and what they print is handed to Claude.

Install

Needs Claude Code 2.1.292 or later, git, bash and a project under git. The browser dashboard also needs Node 18 or later, or Bun.

claude plugin marketplace add bn-l/claude-autoresearch-mod
claude plugin install autoresearch@bn-l

In the project, run /autoresearch <goal>, for example /autoresearch make sort.js faster. /autoresearch alone prints the help, and off, clear, web and dashboard are its other arguments. To try it on a toy first, copy the repository’s examples/sort-bench folder somewhere, make it a git repository and start there.

There are two settings, listed by claude plugin configure autoresearch. compactAtPercent (default 70) compacts between iterations once the context is that full. questionWaitMinutes (default 5) is how long the loop waits for your answer to a question. 0 turns either off, and --config questionWaitMinutes=0 on the install command sets one from the start. A .auto/config.json in the project can also set maxIterations to cap the runs and workingDir to work in another folder.

How it works

/autoresearch turns the mode on and submits a kickoff prompt as if you had typed it. With no .auto/prompt.md in the folder yet, the kickoff is the plugin’s setup skill plus your goal; once that rules file exists, the loop starts from it. While the mode is on, the mod adds a section to the system prompt that tells Claude to use the three tools and not to stop until interrupted. Each time a turn ends with the loop still going, it submits a resume prompt, again as your message. With the mode off, the tools are deferred and refused.

It runs processes with your permissions, in the project folder, through bash: the benchmark command Claude passes to run_experiment, .auto/checks.sh, your hook scripts (30-second limit, up to 8 KB of output passed on) and git. A kept run gets git add -A and git commit, so everything in the working tree goes into that commit. A discarded or crashed run gets git checkout -- . and git clean -fd, which undo edits and delete untracked files, sparing ignored files, .auto/ and autoresearch.*. That is why it asks about uncommitted changes before it starts.

It creates .auto/log.jsonl and appends a line for every run and for every hook script that runs. Each run’s full output goes to a file in your temp folder, and the tool result keeps only its tail. In Claude Code’s plugin store it keeps, per session and folder, whether the mode is on, the stashes it made and the state of a running loop. The rules in .auto/prompt.md and the backlog in .auto/ideas.md are files Claude writes and reads; the mod points it at them.

The mod’s HTTP calls all go to 127.0.0.1. /autoresearch web starts the plugin’s server/dashboard-server.mjs under node or bun, opens the page with open or xdg-open, and after each logged run POSTs to that helper, with a token the helper printed, so the page refreshes. /autoresearch off, clear or the end of the session stops the helper.

Every iteration is model work, so a loop uses tokens and plan usage for as long as it runs. When it compacts between iterations with the mode on, it answers the compaction itself, with no model call: a summary rebuilt from the files on disk (goal, metric, rules, ideas, the last 50 runs) plus the messages of the iteration in progress.

While the mode is on, workflow agents and teammates are refused and background subagents run in the foreground, so nothing else edits the tree between a run and its keep or revert. Subagents cannot call the experiment tools.

How the loop stops

• maxIterations in .auto/config.json: once that many runs are logged since the last init_experiment, the mode turns off and the turn ends.
• /autoresearch off (or /autoresearch-off) turns the mode off, ends the turn in progress and stops the browser dashboard.
• /autoresearch clear asks first, then deletes the session log and turns the mode off.
• Esc pauses the loop. The status line says so, and your next message carries on.
• The mod stops resuming after 200 automatic resume turns.
• Quitting Claude Code ends the loop. If the process dies or restarts instead, the loop picks up again when that session starts.

Limitations

• Without maxIterations the loop has no end of its own: the prompt tells Claude to keep going until interrupted, through runs of discards.
• /autoresearch dashboard opens only where a terminal draws the session. The author documents no other surface.
• The browser dashboard is optional and needs node or bun on your PATH.