autoloop

The autoresearch loop for the rest of us. Same core pattern — baseline, attempt, check, keep or discard, repeat — but for any repo: code, docs, websites, tests, pipelines.

You bring the AI agent (Claude Code, Codex, etc.). This repo tells it what to do.

Quick start

1. Copy program.md, autoloop.yaml, and these .gitignore rules into your repo:

   results.tsv
   artifacts/

2. Fill in autoloop.yaml:

   goal: "Improve homepage copy and layout clarity"
   
   editable:
     - src/pages/index.html
     - src/styles/main.css
   
   checks: auto
   
   max_attempts: 5
   time_budget: 30m

   checks: auto detects available checks from your project config and shows them for confirmation before starting.

3. Point your agent at it:

   Read program.md and autoloop.yaml, then start the loop.
   

4. Come back later. Review results.tsv, artifacts/, and the git log.

Use it when

• Your repo has local checks that can run unattended
• You can define a numeric metric or at least inspectable artifacts
• You can bound the edit scope to a known set of files
• You want the agent to keep trying small improvements without asking after every attempt

Don't use it when

• The goal has no observable output, no useful checks, and no clear artifacts
• The work would cause unsafe or irreversible external side effects
• The editable scope is too broad to trust unattended changes
• The repo is already in a broken or ambiguous local state

If you cannot tell whether a change is better by checks, artifacts, or a metric, autoloop will have low confidence and may not be a good fit.

What a successful run looks like

Example results.tsv:

attempt	status	checks	metric_value	commit	artifacts	rationale
baseline	baseline	pass	—	a1b2c3d	artifacts/baseline/	Baseline run
001	discard	pass	—	—	artifacts/attempt-001/	Headline rewrite was cleaner but not clearly better overall
002	keep	pass	—	b2c3d4e	artifacts/attempt-002/	Improved heading hierarchy and simplified CTA copy
003	discard	fail	—	—	artifacts/attempt-003/	Build failed after nav refactor
004	keep	pass	—	c3d4e5f	artifacts/attempt-004/	Reduced CSS duplication and improved spacing consistency

Example git log --oneline:

c3d4e5f attempt 004: simplify spacing system
b2c3d4e attempt 002: improve heading hierarchy and CTA copy
91aa120 existing repo commit before autoloop started

Adding a metric later

Start with checks: auto and no metric. Once the loop works, add a structured metric to move keep/discard decisions from agent judgment to a deterministic numeric signal:

metric:
  command: "lighthouse http://localhost:3000 --output json"
  format: json
  path: "categories.accessibility.score"
  direction: higher
  improve_by: 0.01

Optional early stopping:

done_when:
  operator: ">="
  value: 0.95

Config reference

Field	Required	Default	Description
goal	yes	—	Natural language description of what to improve
editable	yes	—	Repo-root-relative file paths or globs
companion_editable	no	[]	Companion or generated files allowed as direct consequences of in-scope edits
checks	no	auto	auto, none, or list of commands
run	no	[]	Commands that produce inspectable output
metric	no	null	Structured metric config (command, format, direction required)
done_when	no	null	Metric threshold for early stop; requires metric
max_attempts	no	10	Stop after N attempts. 0 = unlimited
time_budget	no	60m	Stop after duration. Xm, Xh, or 0

Design principles

• Instruction-driven — the framework is program.md, not code
• Agent-agnostic — works with any agent that can read markdown and use tools
• Safe by default — bounded attempts, scoped edits, no external side effects
• Honest about limits — safety is instructed, not runtime-enforced in v1