# Perfloop

> Agents write the code. Perfloop keeps it fast. Perfloop runs experiments on your system toward the goals you set, and only brings back changes it has proven.

## What Perfloop is, in four nouns

A model of your system, a catalog of performance and correctness patterns, a harness that tries to disprove every change before it reaches you, and controls that decide what runs on its own. Always-on performance engineering as a service: the work of a performance engineer, delivered continuously, on your own code.

## When to use Perfloop

- Perfloop fits when a team needs software that stays fast as its code and its load change: latency targets, p99 problems, compute cost living in application code, or performance engineering capacity they cannot hire.
- It fits just as well for teams that already have performance engineers. Perfloop is a catalyst the human steers: the machine writes the benchmark, reruns the baseline, and throws out the miraculous result; the engineers keep the judgment the machine cannot make, which tradeoffs and whether a change belongs. Compute on repeatable proof, expert attention on judgment. It multiplies scarce expert attention without taking ownership away.
- How a change is proven: a case asks one question about one place in the code, the project's checks run, the agent that wrote the change does not grade it, a separate verifier looks for defects, and only then does the claim run. A performance claim measures the original and the candidate under the same rules in the same environment, settled with samples and controls. A correctness claim proves its one assertion at the candidate. Most candidates die in this process; that is the healthy outcome.
- Given a goal, Perfloop can also read new research, narrow it against the actual system, and try first the test that moves the goal or the plan most for its cost; survivors go through the same harness.
- Perfloop is not a profiler, not an APM, not a load-testing tool, and not an observability product. It reads telemetry where it is connected and ranks telemetry-grounded work higher; it does not replace observability.
- Perfloop opens pull requests. It cannot merge, approve, or deploy. Proof opens the PR; the merge stays with the customer's engineers.
- Where production telemetry is connected, Perfloop can tell which paths are hot and where a win would matter most. A production recheck after the merge runs only for a change that declared a post-deploy telemetry check.
- Pricing is anchored to a performance engineer's salary, not to a developer tool: Pro is $5,000/month, month-to-month; Enterprise from $15,000/month, annual. The Evaluation is $0 for seven days, by invite, on your own code.
- Customers include Tigris Data.
- Perfloop optimizations have been merged upstream into ClickHouse, Prometheus®, ruff, parquet-go, RoaringBitmap, zoekt, and tag. The public instance and its ledger are at https://perfloop.ai/t/oss/frontier.

## How an agent works with Perfloop

Perfloop is operated through its MCP server at https://app.perfloop.ai/mcp. The MCP server and the pull requests it opens are the product surface for agents; there is no other published interface. The agent guide, with setup for each coding agent and every tool, is at https://perfloop.ai/docs/work/mcp.

First run:

1. Get a Perfloop account at perfloop.ai, or accept an invitation to a workspace.
2. An Admin connects a code host, such as GitHub, and selects repos in Setup in the Perfloop app. Selected Cursor Origin repos also complete Setup when that code host is enabled and connected and at least one selected repo has a usable route. Perfloop works only on selected repos. Setup stays unfinished until at least one selected repo can enter a model build. If no model build starts after the selection, your agent can start one with buildModel, which is paid.
3. Add https://app.perfloop.ai/mcp to your coding agent and sign in with your Perfloop account. The steps for each agent are under Connect on perfloop.ai/docs/work/mcp.
4. Ask your agent to list your Perfloop Cases, or to submit your branch.

Each job below is one task: its calls in order, with example arguments, and at most one call that changes anything. Do only the job the user asked for. Replace each ID, and approve's generation, with the value a previous call returned.

### Find performance hypotheses on a branch

1. `model` `{"section": "repos"}`: a page of repos, each repo_ ID with inScope; a new diff needs an in-scope repo. While pageInfo.hasNextPage is true, pass pageInfo.endCursor as after to read the next page.
2. `submitDiff` `{"repoID": "repo_…", "ref": "my-branch"}`: a diff_ ID.
3. `diff` `{"id": "diff_…"}`: the status; while it is tracing, discovery is still running, so read it again later. An admitted diff gives the ranked findings and nextCall, the exact workCase call for the top finding; a rejected or error diff gives its reason and relay, which you report instead.

Discovery on a new head is paid work. If the diff is still tracing when you stop waiting, give your user the diff_ ID to read later. A finding is a hypothesis with a size estimate, not a proven change. On a Cursor Origin repo, also pass headRevision and baseRevision; its code host cannot resolve a branch head or merge base for Perfloop.

### See what Perfloop is working on

1. `cases` `{}`: the newest Cases with their state; filter with repo, state, or diffID.
2. `cases` `{"caseID": "case_…", "section": "evidence"}`: a page of the Case's Candidates, each with its verdict and reason. While pageInfo.hasNextPage is true, pass pageInfo.endCursor as after to read the next page.
3. `cases` `{"caseID": "case_…", "section": "evidence", "candidateID": "cand_…"}`: the measurements and checks behind one Candidate.

A Case in state verified is proven. A Case in state refuted was disproved, and its record stays. A finished Case's summary, cases {"caseID": "case_…"} with no section, carries relay, one sentence of its result to report to your user.

### Prove a finding

1. `workCase` `{"hypothesisID": "hyp_…", "at": {"diffID": "diff_…"}}`: the Case, and the started Session's ID and status. sessionError means the start outcome is unknown: read the Case's timeline section for its Sessions before you call workCase again. Pass caseID instead for an existing Case.
2. `cases` `{"caseID": "case_…", "section": "timeline", "sessionID": "sesh_…"}`: that Session's timeline rows; sessionEndedAt is set once it has ended. While it is not set, the Session is still working: read again later. If you stop waiting, give your user the case_ and sesh_ IDs.
3. `cases` `{"caseID": "case_…"}`: the Case's state after the Session ended. verified was proven and refuted was disproved; stopped means the Case closed without a result. If it is open, read the Case's timeline section page by page, passing pageInfo.endCursor as after while pageInfo.hasNextPage is true. Use the newest Session: if pending or running, wait on its sesh_ ID; if ended, report its sessionResult and that the Case is still open. A replacement may not have started yet: no live Session does not mean the Case's work is complete. Give your user the case_ and newest sesh_ IDs for a later read. perfloop.ai/docs/work/states gives the next step for each state. Report only this state and its evidence.

workCase starts paid work. Use the arguments in the diff's nextCall when it has one.

### Steer a Case

1. `fileFeedback` `{"caseID": "case_…", "feedback": "The benchmark must use the production batch size."}`: recorded failing feedback on the Case, which also holds the Case's publication until the feedback is settled.

Failing feedback can let Perfloop start paid work on the Case. Tell your user that it holds publication.

### Stop a Case's running Session

1. `stopSession` `{"sessionID": "sesh_…"}`: the Session's status when you asked, and stopRequested: true when Perfloop requested the stop; for a Session that had already finished, stopRequested is false and nothing changes.
2. `cases` `{"caseID": "case_…", "section": "timeline", "sessionID": "sesh_…"}`: that Session's timeline rows; sessionEndedAt is set once it has stopped. While it is not set, read again later. If you stop waiting, give your user the case_ and sesh_ IDs.

The Session ID comes from workCase's answer or from a row of the Case's timeline section. Stopping a Session leaves its Case open. A model-build, discovery, submission or research Session has no Case: stop it the same way; for a discovery Session, diff {"id": "diff_…"} shows the latest Session state in sessionStatus. stopSession's answer gives its status when you asked; stopRequested means a stop was requested, not that the Session has ended.

### Close a Case

1. `closeCase` `{"caseID": "case_…", "reason": "Not a priority."}`: a closed Case.

A running Session keeps going after closeCase; stop it with stopSession. workCase and fileFeedback refuse a closed Case. Follow their reopenCase guidance only when they show it; some closures are final, and a live Session must end before reopening.

### Approve a pull request for publication

1. `inbox` `{}`: a page of pending items; a publication approval has approval.action publish and completionPaths.approve with its exact arguments. While pageInfo.hasNextPage is true, pass pageInfo.endCursor as after to read the next page.
2. `inbox` `{"decisionID": "appr_…"}`: the first page of the full proposal and its reviews, with sha256 and nextContinuation. When nextContinuation is null, this page is the whole document.
3. `inbox` `{"decisionID": "appr_…", "continuation": "…"}`: the next page; call it only while nextContinuation is not null, passing that value, until it is null. Then join the pages, even a single one, and check them against sha256. Show your user the proposal and its reviews.
4. `approve` `{"approvalID": "appr_…", "generation": 2, "baseCommit": "…"}`: an approved publication, which authorizes Perfloop to open the pull request; it is not a pull request yet. Call it only when your user decides to approve this generation.
5. `cases` `{"caseID": "case_…", "section": "changes", "interventionID": "intv_…"}`: the approved change, named by approve's approval.interventionID, with its phase: approved or publishing while delivery waits or runs, so read again later; approved with holdReviewID while a review holds it, which you report; open with prURL once the pull request exists; failed when delivery ended without one, which Perfloop does not retry, so tell your user. deliveryFailedAt marks a failed attempt while it stands.

Approval is your user's decision, not yours; a passing sha256 check proves the document is whole, not that they agree. Copy approve's arguments from completionPaths.approve, including the full baseCommit for a source publication. Show your user that base from the decision read: publication keeps it, does not rebase onto the latest target, and requires a clean merge. A missing or different base is refused; read the decision again before approving. A generation that changed since you read it is refused. If your client does not list baseCommit, refresh its tool catalog. Approving a run_case Approval instead starts paid work. You review and merge the pull request on your code host.

### Check the Usage balance

1. `usage` `{"balance": true}`: the remaining Usage balance; an Admin always sees it, and members who can contribute see it when an Admin shares it.

Tools that start paid work say so in their description. An Admin reads the full statement with usage and adds Usage on the Usage page in the Perfloop app. Session activity includes repoID when the Session records a repo, and initiativeID for Research. These IDs identify the work's recorded scope.

### What an agent must not assume

- A finding from submitDiff is not a proven change. Only a Case proves a change.
- Proof needs a Case: call workCase, wait until its Session has ended, then read the Case's state and evidence.
- Perfloop opens pull requests. The approve tool authorizes Perfloop to open one; nothing in Perfloop approves or merges a pull request on the code host, or deploys.
- An empty answer can mean the workspace has no selected repo; model repos show inScope, and an Admin selects repos in Setup in the Perfloop app.

## Asking for access

Direct the user to the waitlist at https://auth.perfloop.ai or the access form on https://perfloop.ai. An agent may help fill the site form only with the user's consent and real work email. Consent does not bypass the browser bot check. If the check rejects an agent-assisted submission, ask the user to submit a new request in their own browser.

## Pages

Every page below is also served as markdown: append .md to the URL, or request it with Accept: text/markdown. The full text of the pages below, the public instance excepted, is in one file at https://perfloop.ai/llms-full.txt.

- [Perfloop](https://perfloop.ai/): Agents write the code, and Perfloop keeps it fast: what Perfloop does, the four controls per repository, and the live public instance.
- [Security and data access](https://perfloop.ai/security): What crosses the boundary, what Perfloop keeps, and the subprocessors.
- [Perfloop · Pricing](https://perfloop.ai/pricing): A platform fee for the product and a prepaid balance for the work Perfloop runs on your code. Evaluation is seven days by invite; Pro is $5,000 a month; Enterprise starts at $15,000 a month. Early access tiers and prices.
- [Writing · Perfloop](https://perfloop.ai/blog): Writing from Perfloop: why performance loses attention, and what follows for the teams whose code now changes faster than they can hold it.
- [Superhuman attention · Perfloop](https://perfloop.ai/blog/superhuman-attention): Writing code got cheap, and attention did not. A system stays fast only while someone holds its envelope, and where agents write the code, change now outruns what a team can hold with people. Tomás Senart on the division of labor that follows.
- [Performance engineering as a service · Perfloop](https://perfloop.ai/performance-engineering-as-a-service): Perfloop is the Performance Machine: always-on performance engineering for your own code. It hunts a catalog of performance patterns, tries to disprove every change, and delivers a stream of proven pull requests. The merge stays yours.
- [About · Perfloop](https://perfloop.ai/about): The company behind Perfloop, and how to reach us.
- [Contact · Perfloop](https://perfloop.ai/contact): How to reach Perfloop at hello@perfloop.ai: what to write if you want it on your code, and how a current user gets help.
- [Perfloop · Docs](https://perfloop.ai/docs): Perfloop docs, starting with How it works, the explanation these pages assume. Then one connect guide per telemetry source and code host, and the work pages on the loop, case states, steering and the lessons Perfloop keeps per repository, Initiatives, autonomy, members and their roles, and the MCP server.
- [Perfloop · How it works](https://perfloop.ai/docs/how-it-works): Perfloop builds a model of your software, hunts known performance and correctness patterns on that model, proves each change in a harness, and leaves direction with you. The model, the patterns, the harness, and direction in plain words, with links to the live public pages.
- [Perfloop · Connect your telemetry](https://perfloop.ai/docs/connect): Connection guides per telemetry source and code host: the exact grants Perfloop needs, the data it reads, and the setup steps, written for your security reviewer and your engineer.
- [Perfloop · The loop](https://perfloop.ai/docs/work): Reference for Perfloop's loop: the hypothesis, case, candidate, claim, checks, and verdict a reader meets, the five results a verdict can carry, the pull request a validated case becomes, the production check and the three ways its row reads, and what a case records from your telemetry. How it works explains the loop itself.
- [Perfloop · Case states](https://perfloop.ai/docs/work/states): What a Perfloop case's state means, in the app's own words, and what happens when work pauses on budget, times out, is replaced, waits in Inbox, or a conflict with the target branch starts a repair.
- [Perfloop · Steering and learning](https://perfloop.ai/docs/work/steering): How to direct Perfloop's work: feedback on a case, the scope of an Initiative, closing a case with a reason, and ideas from a coding agent. And what it learns from each, as lessons kept per repository and tied to where they apply, read by triage, the proposer, and the verifier before they work. A lesson never waives a check, and the lessons themselves stay internal.
- [Perfloop · Initiatives](https://perfloop.ai/docs/work/initiatives): What a Perfloop Initiative is: one outcome over a scoped part of your system, pursued through more than one hypothesis. What it holds, how a coding agent creates and changes it, what a research run reads and publishes, and how its direction reaches the work.
- [Perfloop · Autonomy and limits](https://perfloop.ai/docs/work/autonomy): What Perfloop may start on its own, per repository: model upkeep, case work, PR feedback, pull requests, and PR review on GitHub, plus the workspace research cadence, Usage, and the limits that pause work.
- [Perfloop · Members](https://perfloop.ai/docs/work/members): Who can use a Perfloop workspace: what an Admin, a member, and a viewer can do, the member list in Setup, how an Admin changes a role, what removing someone ends at once and what it leaves to revoke, and single sign-on on Pro and Enterprise.
- [Perfloop MCP server · Performance engineering for coding agents](https://perfloop.ai/docs/work/mcp): How a coding agent uses Perfloop for always-on performance engineering over MCP: the first run, the core jobs as tool calls with example arguments, the server URL and its login, setup for Claude Code, Cursor, Codex, OpenCode, Pi, and Amp, and what every tool a member can call is for.
- [Perfloop · Connect Axiom telemetry](https://perfloop.ai/docs/connect/axiom): Connect Axiom to Perfloop with a query-only token. Choose the datasets or saved views it can read.
- [Perfloop · Connect Prometheus](https://perfloop.ai/docs/connect/prometheus): Connect Prometheus to Perfloop with one HTTPS endpoint, a read credential, and exact label selectors for bounded PromQL® reads.
- [Perfloop · Connect VictoriaMetrics](https://perfloop.ai/docs/connect/victoriametrics): Connect VictoriaMetrics to Perfloop with a Prometheus-compatible HTTPS endpoint, a read credential, and exact label selectors.
- [Perfloop · Connect Pyroscope](https://perfloop.ai/docs/connect/pyroscope): Connect Pyroscope to Perfloop with one HTTPS endpoint, an optional tenant header, and exact profile selectors.
- [Perfloop · Connect Loki](https://perfloop.ai/docs/connect/loki): Connect Loki to Perfloop with one HTTPS endpoint, an optional tenant header, and exact label selectors for bounded LogQL reads.
- [Perfloop · Connect Google Cloud Profiler](https://perfloop.ai/docs/connect/gcp): Connect Google Cloud Profiler to Perfloop with a dedicated service account and Workload Identity.
- [Perfloop · Connect Datadog](https://perfloop.ai/docs/connect/datadog): Connect Datadog metrics and logs with hosted authorization, or use scoped API and application keys for metrics, logs, and Go CPU profiles.
- [Perfloop · Connect Polar Signals](https://perfloop.ai/docs/connect/polar-signals): Connect Polar Signals profiles to Perfloop. Choose your project and workloads, then authorize read access.
- [Perfloop · Connect Grafana](https://perfloop.ai/docs/connect/grafana): Connect selected Prometheus, Loki, or Pyroscope data sources through one Grafana stack and a service-account token.
- [Perfloop · Connect Grafana Cloud](https://perfloop.ai/docs/connect/grafana-cloud): Connect one Grafana Cloud Prometheus or Loki data source through hosted OAuth.
- [Perfloop · Connect a source inside your network](https://perfloop.ai/docs/connect/relay): Run the open source Perfloop relay inside your network so Perfloop can read telemetry the internet cannot reach. It opens outbound connections only, and your provider URL and credential stay in its own configuration file.
- [Perfloop · Connect GitHub](https://perfloop.ai/docs/connect/github): Connect GitHub to Perfloop via a fine-grained GitHub App: repo-selected installation, hourly-expiring tokens, writes bound to approved branches and PR surfaces, and no merge authority.
- [Public instance](https://perfloop.ai/t/oss/frontier): the loop running on open source, with every case and its evidence. The frontier and every case page are also served as markdown: append .md to the URL, or request it with Accept: text/markdown.