The loop.

The loop's parts, in the words the app prints. How it works explains what it does; this page names the objects and the results.

Press ⌘K (Ctrl+K on Linux and Windows) on any page of the app, or Search in the rail, to go to a page, repo, service, workload, case, Initiative, or pattern by name. On a phone, tap Search in the top bar. Start with repo:, case:, or another kind to search one kind. Paste a Perfloop link or a case id to open it.

The objects

• Hypothesis. One falsifiable question about one place in the code: a performance pattern that could be costing time, a correctness pattern that could be breaking an invariant, or a security flaw at a trust boundary. Perfloop finds them on the model of your repository; a coding agent can submit one with submitIdea. Cases lists the open ones, each with a Size: S, M, L, XL, or Unknown. Size estimates the work to make and check a change, not hours. Filter Cases by repo, file, workload, service, pattern, or origin; state: picks case states.

• Case. The work on one hypothesis. You start it with Work this case, a coding agent with workCase, or Perfloop starts it on its own when automatic case work (Keep working) is on for the repository. It runs in a Session, in a sandbox with your repository checked out. During case work, Perfloop can read other public GitHub repos for context. This adds no write access or access to unconnected private repos. When it ends, the case page records what it found or why it stopped.

• Candidate. One change with its proof contract: the commit, the claims it makes, and the checks it declares.

• Claim. What a candidate says its change does. A performance claim names the workload and the metrics that should move. A correctness claim names the property that must hold, including a security contract. A bug fix or security repair must fail its test on the original code and pass after the change.

• Checks. Your repository's own commands, run on the candidate.

• Verdict. The case's current result, from the checks, the claims, and an independent verifier that tries to find a defect. The agent that wrote the change never grades it.

Before choosing automatic work, Perfloop checks open upstream pull requests and linked issues. It defers work that would repeat the same improvement and records the link. It can still choose useful distinct work and explain the difference.

Results

A verdict carries one of five results. These are the case's result, carried on its verdict, and not the state it is in.

• VALIDATED. Every check passed and every claim held, its metrics measured for performance or its property asserted for correctness or security.

• NO_EFFECT. Every metric the change claimed was measured, at least one did not meet its bar, and nothing regressed.

• REGRESSED. A metric the change claimed moved the wrong way, or a guardrail beside it lost more than the change allowed and the measurement confirmed the loss.

• INCONCLUSIVE. A check failed, a metric the change claimed could not be measured, or the verifier found a defect, so nothing settles it. It is also what a case reads before it has a result of its own.

• REFUTED. The hypothesis itself was disproved, and the case stays closed with that evidence.

Only VALIDATED is usable. Where the case goes after a result is its state rather than its result, and Case states has that.

If Measurements reads UNRESOLVED, the measurements do not establish whether the change met its requirements. Open Statistics for the measurement bounds. Work can end inconclusively with the evidence needed to decide the remaining requirement. The requirement stays unchanged.

The pull request

A validated case can become a pull request. The Pull requests control decides whether Perfloop opens it or it waits in Inbox. Perfloop keeps it current after feedback, cannot approve or merge it, and the merge stays with you.

Before proposing a pull request, Perfloop compares the change with open upstream work. If it finds the same improvement, it keeps a draft and records a publication hold with a link. A useful different change can still be proposed; its description links the related work and explains the difference.

The initial description follows your repo's template and contribution rules and reports that candidate's proof. If you edit the description, once Perfloop sees the edit it keeps your text without reposting a replacement description as a comment.

For performance work, unless your repo's rules say otherwise, when no benchmark in your repo shows the change's effect, the pull request also adds a small benchmark in your repo's own style. The description names its file or command so a maintainer can run it.

The pull request reports which checks ran on the change. Checks not run by Perfloop stay with your CI.

After approval, the change reads PR publishing while Perfloop delivers it. If a delivery attempt fails, it shows delivery failed and when. Perfloop retries; you do not need to act.

Request changes holds an approved change. It shows held by review and does not deliver. Allow publication in Inbox lifts the hold; Close case on the same Inbox item declines it. Rejecting a Candidate publication ends the Case without repair work. Use Request changes to request a repair instead.

Perfloop commits as Perfloop Agent <agent@perfloop.ai>. Sign-off follows your repo's contribution rules. Commits already on an open pull request, including your maintainers', stay as they are.

Member sign-off is off by default. When an Admin turns it on, each new commit gets a Signed-off-by line with the approving member's display name and account email, unless that sign-off is already present. Under automatic publishing, the configured Admin signs off, as Autonomy and limits describes. That name and email become part of the repo's public commit history. If an older candidate cannot take the sign-off, publication returns to Inbox with an error before anything is pushed; recreate that candidate and approve again.

When your repo's instructions require a person to write the pull request description or open an issue, the case still verifies the change and records a publication hold with a draft description. Your coding agent can open the pull request: cases with codeChanges and link returns a ten-minute link to the whole change and the commit it applies to.

The production check

A candidate can declare one production check: the production surface its change should move. After the merge, and while the case is open, deterministic code decides it against production telemetry until it confirms the win or times out; a case you closed before then does not wait. While it waits, the case page shows Production check, which reads one of four ways:

• watching production telemetry, while a check is running.

• holding, when the check waits on a condition it names, such as no connected telemetry source.

• last check failed, when one did not complete.

• production measured no win, when a check measured and found none. Perfloop stops rechecking and holds the case for your review.

The row goes when the check confirms the win, when it times out, and when you close the case. A no-win hold keeps its row. The verdict carries the outcome under What happened. The queries each check ran are under Recorded queries.

Production telemetry as evidence

Perfloop reads metrics, logs, traces, and profiles from a connected telemetry source: aggregates over each kind, and scoped entries where the source returns them. One guide per source under Connect your systems says what it returns and what Perfloop keeps. Perfloop ranks telemetry-grounded work higher on Cases.

A Watch checks a rule on something in your Model, such as a service or its telemetry. The Watches page shows the rule, its latest check, and the work that followed. When the evidence points to another connected repo that allows automatic Case work, Perfloop can open a Case there. Usage links each Session to the Watch that caused it.

When telemetry justified a hypothesis, its case keeps the query, the result, the environment, and the window. A coding agent reads them with cases under observations. When the hypothesis cites an earlier Perfloop pull request, the case shows Follows change from that case.

Where no telemetry covers a repo or an operation, Perfloop profiles a workload itself: one of your benchmarks or tests, or a small workload it writes, run once in its sandbox. The case shows it as a workload profile. It says where that workload spent its time, not what happens in production.

Also in this section: Quickstart, Performance, Bugs, Security, Case states, Pull requests, Steering and learning, Initiatives, Autonomy and limits, Members, The MCP server, and Events.

Questions: hello@perfloop.ai