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 or correctness property 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 →connect your systems →the loop's objects →

Patterns are the catalog of mechanisms.

A pattern names one known way that code wastes time or breaks a rule it must keep. Perfloop checks your code against its catalog of patterns, starting where the model says the work matters. A performance change is proved by measurement before and after it. A correctness change is proved by a case that fails before it and passes after it.

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 →hypotheses and cases →

The harness is the proof step.

A case that finds a change ends in a candidate: a change to the source, the benchmark that should move or the assertion that must hold, 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, and in a sandbox it runs the benchmark on the candidate and the commit it came from, or proves the assertion at the candidate.

The agent that proposes a change never grades it. The checks and the proof run in the sandbox, and an independent verifier with fresh context tries to disprove the change before any result exists. A case is validated only when the checks pass, the verifier finds no defect, and the claim 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 proof, the verification. The maintainer decides whether to merge. The links below open one merged change and its case, end to end.

open a merged case →ClickHouse #113899 →what a verdict can say →case states →

Direction is the part you keep.

Every repository in scope has up to five controls that decide what runs on its own: keeping the model current, starting case work, handling feedback on open pull requests, opening the pull request when a case proves, and reviewing new pull requests, where available. No control 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. A limit Perfloop sets for each workspace caps how many automatic cases run at once.

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 picks the experiment that closes the most of your goal, or changes the plan the most, for its cost. Accepted hypotheses become cases. Existing cases join an initiative when they serve its goal. Set a cadence and it recurs; leave it off and research runs when you ask.

Perfloop weighs the target's maintenance direction and the public API a proposed change would add when choosing what to work on next. An accepted replacement plan can lower its priority. Unknown cost or workload size stays a question for the case to measure. Admission stops duplicate, unsafe or out-of-scope work; independent verification decides whether a change proves its claim.

autonomy and limits →Initiatives →