Getting started

From a new account to your first reviewed run, in seven steps.

Peractor runs AI coding agents through a pipeline you define. The work happens in phases, you review between them, and you can watch every step as it happens — from your editor, a browser, your Mac, or your phone.

This guide gets you from nothing to a finished, reviewed piece of work. It takes about ten minutes, and most of the steps have a working default you can skip.

1. Create an account and an organization

Sign up with an email address, or with GitHub, Google, or Linear. That gives you a personal account.

Then create an organization, or join one with an invite link. The organization is the shared space your team works in — it owns your projects, tasks, runs, connected services, and billing. You can belong to as many as you like. See Organizations & members.

2. Install the editor extension

The editor is where most people do the deep work. Install the Peractor extension in VS Code or one of its forks, then click Sign in in the Peractor sidebar. It opens this site in your browser and hands the session back — you never type a password into your editor.

Prefer a browser, your phone, or the Mac app? Every surface can do this. See Peractor on your devices.

3. Let runs push to your repository

Runs work on real git branches, so Peractor needs permission to push. Open Settings → Git access and pick one:

• The Peractor GitHub App — recommended for GitHub. Each run gets a short-lived token scoped to exactly its own repository, and the app opens and merges the pull requests.
• A token or SSH key — works with GitLab, Bitbucket, and any self-hosted remote.

Details in Git & credentials.

4. Connect your repository to a project

A project is the workspace for one codebase. In the editor, choose Connect this repo to a project. Peractor creates the project and writes a small peractorrc.json file at the root of your repository — the only file it ever keeps there. Everything else lives on the server and is edited in the app.

5. Take the setup wizard, or skip it

The wizard walks seven optional steps: the agent to use, the kind of work you do, git access, personas, workflows, issue trackers, and notifications. Nothing is saved until you press Complete setup, so you can back out at any point.

Every step has a sensible default. Skip all of them and you still have a working spec → coding → merge pipeline.

If you would rather describe what you want in your own words, the assistant can set the same things up from a conversation.

6. Start a run

Write a task, or sync one in from your tracker. Pick a workflow and press Run.

The live session opens. You see what the agent is thinking, every file it changes as a diff, every command it runs, and the cost ticking up per phase. When a phase finishes, the run stops and waits for you.

7. Review, then advance

At the stopping point — we call it a gate — you have two buttons:

• Approve moves the run on to the next phase.
• Request changes sends it back with your note. The agent reworks the same branch and comes back to you.

Review from your editor, a browser, the Mac app, or your phone — whichever is nearest. That loop is the whole product: watch, decide, advance.

Where to go next: Core concepts · Workflows · Gates & reviews