# Quickstart.

From a new account to the first work Perfloop runs on your code, and where its result shows. One task per step, with the page and the button the app shows.

## Steps

### 1 · get an account

Get an account at perfloop.ai. If a teammate invited you to their workspace, accept the invitation.

### 2 · open your workspace

A teammate's invitation signs you in to its workspace. Perfloop then opens Start, which lists the setup steps that remain. An Admin takes step 3.

### 3 · connect GitHub and choose repos

Before you connect, [Security](https://perfloop.ai/security) lists what Perfloop reads, what it keeps, and what it cannot do. In Setup, select **Install Perfloop GitHub App**. On GitHub, choose **Only select repositories** and pick the repos Perfloop may read. Back in Setup, select the repos for Perfloop to work on, then **Save selection**. Perfloop reads and works only on the repos you choose. [Connect GitHub](https://perfloop.ai/docs/connect/github) lists the access the App asks for.

Setup, before a code host is connected.

Setup, after the App is installed: choose repos, then Save selection.

A model build then reads each repo, and the hypotheses worth testing appear on the Cases page. The Model page shows the build. If none starts after you save, select **Build this repo** on the Model page, or ask your coding agent to start one with `buildModel`. A build is paid work.

### what to expect

Many attempts fail the proof; that is expected, and the failed ones stay on record. Start with one Case before you turn on automatic work.

### 4 · connect your coding agent

Add the Perfloop MCP server to your coding agent and sign in with your Perfloop account. The steps for each agent are on [The MCP server](https://perfloop.ai/docs/work/mcp#connect), and in Setup under Coding agents.

Setup, Coding agents: connect to https://app.perfloop.ai/mcp and follow the steps for your agent.

### 5 · start the first work

In Setup under Automatic work, each repo's Case work control, **Keep working**, starts off. While it is off, Perfloop picks no Case on its own. Start the first work in one of two ways:

- **Hand Perfloop a branch or a pull request.** Ask your agent to submit it. The agent calls `submitDiff`, then reads the findings with `diff`. A finding is a hypothesis Perfloop has not yet proven. Ask the agent to prove the one you want; it calls `workCase`. For a pull request, it first asks you to approve running that exact head's build and test code.
- **Start a Case.** Open Cases, open a Case in state PROPOSED, and select **Work this case**. When its case session starts, the Case changes to OPEN. Your coding agent can start a PROPOSED Case too: it calls `workCase` with the Case's `caseID`, or with a `hypothesisID`. A Case found only in a branch or pull request also needs that diff, as above.

The header of a PROPOSED Case: Work this case starts its first case session.

Each is paid work and draws on Usage. For Perfloop to pick and work Cases itself, an Admin selects **Keep working** for the repo and **Save settings**. [Autonomy and limits](https://perfloop.ai/docs/work/autonomy) explains each control.

New work needs a positive Usage balance. Work already in progress can cost more than the balance left. Unpaid Usage carries into the next Usage period. New funds first cover that shortfall.

### 6 · read the results

A Case page shows its state and the evidence behind it. VERIFIED means a change passed its checks, every claim held, and the verifier found nothing. [Case states](https://perfloop.ai/docs/work/states) explains every state and what to do next.

A verified change can become a pull request, or only an issue when an issue is the better contribution, such as a finding the maintainers should fix themselves. The **Pull requests** control starts off, so the proposal waits in Inbox: select **Approve & open PR** (or **Approve & open issue**) or **Reject**. Perfloop opens it on GitHub. You review and merge a pull request as usual; an issue has nothing to merge. Perfloop cannot approve, merge, or deploy.

Inbox: a proven change waits for Approve & open PR, or Reject.

Your agent reads the same results with `cases`, and a submitted change's findings with `diff`.

## Get help

In the app, select **Send feedback** in the side rail (in the menu on a phone), or write to [hello@perfloop.ai](mailto:hello@perfloop.ai?subject=Perfloop%20quickstart). Both reach the Perfloop team.

Also in this section: [The loop](https://perfloop.ai/docs/work), [Case states](https://perfloop.ai/docs/work/states), [Steering and learning](https://perfloop.ai/docs/work/steering), [Initiatives](https://perfloop.ai/docs/work/initiatives), [Autonomy and limits](https://perfloop.ai/docs/work/autonomy), [Members](https://perfloop.ai/docs/work/members), and [The MCP server](https://perfloop.ai/docs/work/mcp).