You edit program.md.
The agent edits the code.
The harness decides.
Tests are frozen and restored before every run. The metric lives in a compiled binary the agent can't reach. Noise is discarded, regressions are rejected.
- one commit per accepted change
- one results.tsv row per experiment — including failures
- stop any time, nothing is thrown away
the loop runs until you stop it
case studies
real measured runs, never illustrations−40.2% ns/op
geomean over the declared benchmarks · six experiments, two genuine keeps
Two real optimizations kept on a maintained library: a pre-sized buffer in Commaf, and strconv.AppendFloat replacing a doubled Sprintf in humanateBytes. A third keep was spurious — the case study says so, and says what was fixed.
read the go case study ↗−25.1% ns/op
geomean over four benchmarks · ten experiments, four kept
The library ships no benchmarks, so the run wrote them and froze them before measuring anything. Biggest win: quote() writes runs of ordinary characters in one call instead of one per character. All four changes at once measure −26.1%.
read the java case study ↗−57.1% cumulative
2.33× faster overall · six experiments, two kept
An ASCII fast path for split_word_bounds, found by noticing two sibling functions disagreed: −90.5% on the one benchmark that can take it. The same run turned up three real defects in the harness itself, all since fixed.
read the rust validation run ↗10.98× faster
11 experiments, 9 kept · a local clone, nothing contributed upstream · the win is unreviewed unsafe pointer work
PEMDocument.swift was idiomatic Swift over Substring.UTF8View — correct, readable and accidentally very slow; the profile put firstIndex(of:) at 63% of the time. All 118 of the library’s own tests pass, and the 13 unsafe sites the harness flagged still want a human and a fuzz run over malformed PEM.
read the swift run and its caveats ↗−92.55%
one commit on the port’s own demo, not a third-party library · KEEP, exit 0
A countWords whose hot loop rebuilds the whole array per character: chars.concat replaced with chars.push. The same live session then discarded a no-op against the advanced baseline and failed a scope violation — all three exit codes in one run.
read the typescript worked example ↗−54.00% ns/op
one commit on the port’s own demo, not a third-party library · KEEP, 2.17× faster
The same counter, built badly on purpose: a regex per character and string concatenation, replaced with charcode comparisons and a Map. The test and the benchmark are restored before every eval, so the behaviour had to survive the change to be scored at all.
read the javascript worked example ↗
SKILL.md
or install it as an agent skill
Every port ships a skill — the whole "Start here" handoff packaged as a SKILL.md your agent loads on its own. Install it once and say "make this repo faster"; the agent picks the right harness, runs init → doctor → baseline, and follows program.md.
works with Claude Code · Codex CLI · Cursor · any agentskills.io-compatible agent
install the autor3search-go skill
npx skills add autor3search/go
then, inside the repo you want faster, tell your agent:
use the autor3search-go skill to optimize this repository
Install and run autor3search-go on this repository, then optimize it. Setup: 0. Run git status. If the working tree has changes, STOP and ask me to commit or stash them first. 1. go install github.com/autor3search/go/cmd/autor3search-go@latest Make sure $(go env GOPATH)/bin is on PATH. 2. autor3search-go init Show me the benchmarks it discovered. If it reports none, STOP and tell me: this tool can only optimize what it can measure. 3. git add -A && git commit -m "autor3search-go init" 4. autor3search-go doctor Show me any warnings. If the machine looks unfit to measure, stop and ask me before continuing. 5. autor3search-go baseline -tag <today, e.g. sep6> Then: 6. Read program.md in this repository, in full. It is your instruction set for the rest of this run. Follow it exactly. Rules for the whole run: - Never edit program.md, .autor3search/config.yaml, results.tsv, or anything the harness writes. They are not yours. - Never pass -force to any autor3search-go command. (I may run `autor3search-go stop -force` myself; that one is mine, not yours.) - One idea per experiment. Commit before each eval. - KEEP means the commit stays. Anything else means git reset --hard HEAD~1. - Print one context line before each experiment, so I can see where you are: [exp <n> | <branch> | vs <measure_commit> | stop: autor3search-go stop] Run the loop until I stop you. I stop you by running `autor3search-go stop` in my own terminal — you will see it as "stop_requested": true in a verdict. When you do: apply that verdict, do not start another experiment, run `autor3search-go report`, summarize what you tried, and exit the loop.
Install and run autor3search-typescript on this repository, then optimize it. Setup: 0. Run git status. If the working tree has changes, STOP and ask me to commit or stash them first. 1. npm install --save-dev @autor3search/typescript@^0.3.0 2. npx autor3search-typescript init Show me the benchmarks it discovered. If it reports none, STOP and tell me: this tool can only optimize what it can measure. 3. git add -A && git commit -m "autor3search-typescript init" 4. npx autor3search-typescript doctor Show me any warnings. If the machine looks unfit to measure, stop and ask me before continuing. 5. npx autor3search-typescript baseline -tag <today, e.g. sep7> This runs your install command once per worktree, so dependency install time and node_modules disk use both double. That is expected. Then: 6. Read program.md in this repository, in full. It is your instruction set for the rest of this run. Follow it exactly. Rules for the whole run: - One hypothesis per commit. Commit before each experiment, then run `npx autor3search-typescript eval --json` and apply its verdict before touching anything else: KEEP means the commit stays; anything else (DISCARD, FAIL, CRASH) means `git reset --hard HEAD~1`. - Never edit program.md, .autor3search/config.yaml, results.tsv, any *.test.*/*.spec.*/*.bench.* file, package.json, a lockfile, or tsconfig.json. They are not yours. - Never pass -force to any autor3search-typescript command. (I may run `autor3search-typescript stop -force` myself; that one is mine, not yours.) - Print one context line before each experiment, so I can see where you are: [exp <n> | <branch> | vs <measure_commit> | stop: npx autor3search-typescript stop] Run the loop until I stop you. I stop you by running `npx autor3search-typescript stop` in my own terminal — you will see it as "stop_requested": true in a verdict. When you do: apply that verdict, do not start another experiment, run `npx autor3search-typescript report`, summarize what you tried, and exit the loop.
Install and run autor3search-javascript on this repository, then optimize it. Setup: 0. Run git status. If the working tree has changes, STOP and ask me to commit or stash them first. 1. npm install -g @autor3search/javascript Or prefix every command below with `npx` instead — either way, keep using the same form for the whole run, so the version that recorded the baseline is the version that scores against it. 2. autor3search-javascript init Show me the benchmarks it discovered. If it reports none, STOP and tell me: this tool can only optimize what it can measure. 3. Review .autor3search/config.yaml and program.md, then: git add -A && git commit -m "autor3search-javascript init" 4. autor3search-javascript doctor Show me any warnings. If the machine looks unfit to measure, stop and ask me before continuing. 5. autor3search-javascript baseline -tag <today, e.g. sep7> Then: 6. Read program.md in this repository, in full. It is your instruction set for the rest of this run. Follow it exactly. Rules for the whole run: - One hypothesis per commit. Commit before each experiment, then run `autor3search-javascript eval --json -desc "<idea>"` and apply its verdict before touching anything else: KEEP means the commit stays; anything else (DISCARD, FAIL, CRASH, ABORTED) means `git reset --hard HEAD~1`. - Never redirect eval's stdout into run.log. The harness already holds that file open, and a second writer destroys the transcript you need when something FAILs. - Never edit program.md, .autor3search/config.yaml, results.tsv, any *.test.* / *.spec.* / *.bench.* file, package.json, a lockfile, or a Vitest/Vite config file. They are not yours. - Never pass -force to any autor3search-javascript command. (I may run `autor3search-javascript stop -force` myself; that one is mine, not yours.) - Print one context line before each experiment, so I can see where you are: [exp <n> | <branch> | vs <measure_commit> | stop: autor3search-javascript stop] Run the loop until I stop you. I stop you by running `autor3search-javascript stop` in my own terminal — you will see it as "stop_requested": true in a verdict. When you do: apply that verdict, do not start another experiment, run `autor3search-javascript report`, summarize what you tried, and exit the loop.
Install and run autor3search-python on this repository, then optimize it. Setup: 0. Run git status. If the working tree has changes, STOP and ask me to commit or stash them first. 1. uv tool install autor3search (or: pipx install autor3search) Already installed? Upgrade first: uv tool upgrade autor3search (or: pipx upgrade autor3search). Versions before 0.4.3 pick the wrong interpreter and doctor fails at step 4. 2. autor3search-python init If .autor3search/config.toml already exists, init will refuse rather than overwrite it; re-run as `autor3search-python init -force` so the config is regenerated. Then show me the `python` line from it — that is the interpreter the benchmarks run under, and it needs pytest and pytest-benchmark. Do this before step 5: the file is hashed at baseline, and editing it afterwards fails every eval with config_changed. Show me the benchmarks it discovered. If it reports none, STOP and tell me: this tool can only optimize what it can measure. 3. git add -A && git commit -m "autor3search-python init" 4. autor3search-python doctor Show me any warnings. If the machine looks unfit to measure, stop and ask me before continuing. 5. autor3search-python baseline -tag <today, e.g. sep7> This copies the repository into a pinned worktree and freezes what the verdict depends on, so it takes a moment. Then: 6. Read program.md in this repository, in full. It is your instruction set for the rest of this run. Follow it exactly. Rules for the whole run: - One hypothesis per commit. Commit before each experiment, then run `autor3search-python eval --json` and apply its verdict before touching anything else: KEEP means the commit stays; anything else (DISCARD, FAIL, CRASH) means `git reset --hard HEAD~1`. - Never edit program.md, .autor3search/config.toml, results.tsv, any test or benchmark file, conftest.py, pyproject.toml, or a lockfile. They are not yours. - Never pass -force to any autor3search-python command once the run has started — not to eval, not to baseline. The single exception is setup step 2, `init -force`, which only regenerates the config before anything is measured. (I may run `autor3search-python stop -force` myself; that one is mine, not yours.) - Print one context line before each experiment, so I can see where you are: [exp <n> | <branch> | vs <measure_commit> | stop: autor3search-python stop] Run the loop until I stop you. I stop you by running `autor3search-python stop` in my own terminal — you will see it as "stop_requested": true in a verdict. When you do: apply that verdict, do not start another experiment, run `autor3search-python report`, summarize what you tried, and exit the loop.
Install and run autor3search-java on this repository, then optimize it.
Setup:
0. Run git status. If the working tree has changes, STOP and ask me to
commit or stash them first.
1. Download the latest release jar and its launcher:
mkdir -p ~/.local/bin
curl -sSL -o ~/.local/bin/autor3search-java.jar \
https://github.com/autor3search/java/releases/latest/download/autor3search-java.jar
curl -sSL -o ~/.local/bin/autor3search-java \
https://github.com/autor3search/java/releases/latest/download/autor3search-java
chmod +x ~/.local/bin/autor3search-java
Make sure ~/.local/bin is on PATH.
2. autor3search-java init
Show me the benchmarks it discovered. If it reports none, STOP and tell me:
this tool can only optimize what it can measure.
3. git add -A && git commit -m "autor3search-java init"
4. autor3search-java doctor
Show me any warnings. If the machine looks unfit to measure, stop and ask me
before continuing.
5. autor3search-java baseline -tag <today, e.g. sep7>
Then:
6. Read program.md in this repository, in full. It is your instruction set for
the rest of this run. Follow it exactly.
Rules for the whole run:
- Never edit program.md, .autor3search/config.yaml, results.tsv, or anything
the harness writes. They are not yours.
- Never pass -force to any autor3search-java command. (I may run
`autor3search-java stop -force` myself; that one is mine, not yours.)
- One idea per experiment. Commit before each eval.
- KEEP means the commit stays. Anything else means git reset --hard HEAD~1.
- Print one context line before each experiment, so I can see where you are:
[exp <n> | <branch> | vs <measure_commit> | stop: autor3search-java stop]
Run the loop until I stop you. I stop you by running `autor3search-java stop` in
my own terminal — you will see it as "stop_requested": true in a verdict.
When you do: apply that verdict, do not start another experiment, run
`autor3search-java report`, summarize what you tried, and exit the loop.Install and run autor3search-csharp on this repository, then optimize it. Setup: 0. Run git status. If the working tree has changes, STOP and ask me to commit or stash them first. 1. dotnet tool install -g Autor3Search Make sure ~/.dotnet/tools is on PATH (on Windows, %USERPROFILE%\.dotnet\tools). If the tool installs but then exits with "You must install .NET to run this application", see "If the tool will not start" in the README and tell me. 2. autor3search-csharp init Show me the benchmarks it discovered. If it reports none, STOP and tell me: this tool can only optimize what it can measure. 3. git add -A && git commit -m "autor3search-csharp init" 4. autor3search-csharp doctor Show me any warnings. If the machine looks unfit to measure, stop and ask me before continuing. 5. autor3search-csharp baseline -tag <today, e.g. sep9> This pins a second worktree and builds it, so build time and disk use both roughly double. That is expected. Then: 6. Read program.md in this repository, in full. It is your instruction set for the rest of this run. Follow it exactly. Rules for the whole run: - Never edit program.md, .autor3search/config.yaml, results.tsv, run.log, or any test or benchmark project. They are not yours. Test and benchmark files are restored from frozen hashes before every eval, so editing them does not fail loudly -- it is silently undone, and costs you the experiment. - Never pass -force to any autor3search-csharp command. (I may run `autor3search-csharp stop -force` myself; that one is mine, not yours.) - One idea per experiment. Commit before each eval. - KEEP means the commit stays. Anything else (DISCARD, FAIL, CRASH) means git reset --hard HEAD~1. - Print one context line before each experiment, so I can see where you are: [exp <n> | <branch> | vs <measure_commit> | stop: autor3search-csharp stop] Run the loop until I stop you. I stop you by running `autor3search-csharp stop` in my own terminal -- you will see it as "stop_requested": true in a verdict. When you do: apply that verdict, do not start another experiment, run `autor3search-csharp report`, summarize what you tried, and exit the loop.
Install and run autor3search-rust on this repository, then optimize it. Setup: 0. Run git status. If the working tree has changes, STOP and ask me to commit or stash them first. 1. cargo install --locked autor3search-rust Make sure ~/.cargo/bin is on PATH. 2. autor3search-rust init Show me the benchmarks it discovered. If it reports none, STOP and tell me: this tool can only optimize what it can measure. 3. git add -A && git commit -m "autor3search-rust init" 4. autor3search-rust doctor Show me any warnings. If the machine looks unfit to measure, stop and ask me before continuing. 5. autor3search-rust baseline --tag <today, e.g. sep6> Then: 6. Read program.md in this repository, in full. It is your instruction set for the rest of this run. Follow it exactly. Rules for the whole run: - Never edit program.md, .autor3search/config.yaml, results.tsv, or anything the harness writes. They are not yours. - Never pass --force to any autor3search-rust command. (I may run `autor3search-rust stop --force` myself; that one is mine, not yours.) - One idea per experiment. Commit before each eval. - KEEP means the commit stays. Anything else means git reset --hard HEAD~1. - Print one context line before each experiment, so I can see where you are: [exp <n> | <branch> | vs <measure_commit> | stop: autor3search-rust stop] Run the loop until I stop you. I stop you by running `autor3search-rust stop` in my own terminal — you will see it as "stop_requested": true in a verdict. When you do: apply that verdict, do not start another experiment, run `autor3search-rust report`, summarize what you tried, and exit the loop.
You are optimizing this Swift repository for performance. Setup (once): 0. Run git status. If the working tree has changes, STOP and ask me to commit or stash them first. 1. brew install autor3search/tap/autor3search-swift (or build from source — see its README.) 2. autor3search-swift init Show me the benchmarks it discovered. If it reports none, STOP and tell me: this tool can only optimize what it can measure. Read its scope warning. If any listed target is fixture data rather than code under test, tell me before going further. 3. git add .autor3search/config.yaml program.md && git commit -m "harness config" 4. autor3search-swift doctor Show me any warnings. If the machine looks unfit to measure, stop and ask me. 5. autor3search-swift baseline --tag <today, e.g. sep18> Then: 6. Read program.md in this repository, in full. It is your instruction set for the rest of this run. Follow it exactly. Rules for the whole run: - Never edit program.md, .autor3search/config.yaml, Package.swift, Package.resolved, results.tsv, or any test or benchmark file. They are not yours. - Never pass --force to any autor3search-swift command. (I may run `autor3search-swift stop --force` myself; that one is mine, not yours.) - One idea per experiment. Commit before each eval. - KEEP means the commit stays. Anything else means git reset --hard HEAD~1. - Print one context line before each experiment: [exp <n> | <branch> | vs <measurementCommit> | stop: autor3search-swift stop] Run the loop until I stop you. I stop you by running `autor3search-swift stop` in my own terminal — you will see it as "stop_requested": true in a verdict. When you do: apply that verdict, do not start another experiment, run `autor3search-swift report`, summarize what you tried, and exit the loop.