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 way software wastes time or breaks an invariant: an extra copy on a hot path, a lock that serializes work that did not need serializing. A resource nobody closes is one too. 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 →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. Every merge counted above took this path; the links below open one of them, 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 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.

autonomy and limits →Initiatives →