How Perfloop
works.

The model is the map of your system.

Perfloop reads the repository and builds a model of what is in it: the services, the packages and symbols inside them, and the hot paths that run through them. With production telemetry connected, the hot paths come from what the system does under load; without it, from the source and its benchmarks.

A case is one falsifiable performance question about one place in the code, tagged with the pattern it tests and, where the model can anchor it, tied to the hot path it sits on. The model is rebuilt as the code changes.

open the public model →

Patterns are the catalog of mechanisms.

A pattern names one way software wastes time: an extra copy on a hot path, a lock that serializes work that did not need serializing. The catalog groups its mechanisms into families, from memory and locality to data access and caching.

Every case is tagged with the mechanism it tests, so each win is also a data point about the mechanism, and the improvement follows from the mechanism rather than from the symptom.

open the Patterns page →proven return, by pattern →

The harness is the proof step.

A case ends in a candidate: a change to the source, the benchmark that should move, and the checks that must still pass. To find out whether the change holds, the harness stands your software up: it runs the checks on the candidate, builds the candidate and the commit it came from in a sandbox, and runs the benchmark on both.

The agent that proposes a change never grades it. The checks and the benchmark run in the sandbox, and an independent verifier with fresh context tries to disprove the change before any performance result exists. A case is validated only when the checks pass, the verifier finds no defect, and the measurement holds.

With production telemetry connected, a recheck after the merge can confirm the win in production or hold the case for review. What ships is a pull request that carries the case: the hypothesis, the measurement, the verification. The maintainer decides whether to merge. Every merge counted above took this path; the links below open one of them, end to end.

open a merged case →ClickHouse #113899 →

Direction is the part you keep.

Every repository in scope has four switches that decide what runs on its own: keeping the model current, starting case work, handling feedback on open pull requests, and opening the pull request when a case proves. Off means Perfloop waits for you. No switch changes the proof bar, and Perfloop can never approve or merge its own work.

With case work on, a triage step reads the open hypotheses and picks the one case most worth running next, with a written reason, and starts one case at a time.

An initiative is research toward a goal you set. The catalog hunts what is already known; research reads what is new: papers and public code from the field, narrowed to what applies to your system. It prefers the cheapest experiment that could prove a hypothesis wrong; accepted hypotheses become cases. Cases already on the frontier join an initiative when they serve its goal. Set a cadence and it recurs; leave it off and research runs when you ask.