# Set up Graphide for a user

These instructions are for a coding agent whose user asked to be set up with
Graphide ("Graphide CI", "Graphide review", "Graphide's PR reviews").
Follow them in order. You do the work; the user clicks through one browser
trip and answers your questions.

Graphide runs a repository's CI on its own faster runners and reviews its
pull requests on GitHub. The two are separate, and each repository gets
only what the user asks for. Setup adds Graphide's MCP server to your agent,
signs the user in, installs Graphide's GitHub App on the repositories they
pick, switches to Graphide CI the ones they say yes to, and turns review on
for the ones they choose.

Reviews come on pull requests. If the user's project lands its changes
without them (straight to the main branch), no review will come: tell the
user, and ask before changing how they work.

## 0. Already connected?

If you already have Graphide's `review_setup` tool (from an MCP server named
`graphide`), skip to step 3.

Do not search Graphide's source code for any of this, even if a copy is on
the machine: these steps are the interface.

## 1. Tell the user

"I'll set up Graphide:

1. I add Graphide to this agent and sign you in. Your browser opens: sign in
   to Graphide, click Allow, then pick your repositories on GitHub's page.
2. You restart this chat once, so I can use Graphide's tools.
3. I check which repositories can move to Graphide CI, ask which to move,
   and switch the ones you say yes to (one pull request each).
4. I ask which repositories to review and turn them on.
5. I tell you about Graphide's agent signals: they are on by default, and
   you can turn them off in Settings.

Graphide keeps a copy of the code of each repository you turn on, to review
it."

Then go on: the user has already asked for this.

## 2. Add Graphide and sign in

The server is `https://mcp.graphide.com` (Streamable HTTP, signed in with
OAuth). Name it `graphide`; if that name is taken by another server, use
`graphide-review`.

Signing in opens the user's browser and waits until they finish: Graphide's
sign-in, the Allow page, then GitHub's install page. That can take a few
minutes, so give the command up to ten minutes, or run it in the background
and wait for it to exit. Tell the user: "Your browser has opened Graphide.
Sign in, click Allow, then choose your repositories on GitHub. I'll carry on
when you're done."

Never ask for or type the user's password.

### Claude Code

```sh
claude mcp add --scope user --transport http graphide https://mcp.graphide.com
```

`claude mcp login` needs a terminal, which your shell is not, so run it under
`script`:

- Linux: `script -qec "claude mcp login graphide" /dev/null`
- macOS: `script -q /dev/null claude mcp login graphide`

It ends with `Authenticated with "graphide"`. This chat cannot see the new
tools until Claude Code starts again, so tell the user: "Graphide is
connected. Type /exit, run `claude -c` in this folder, and say continue."

### Codex

```sh
codex mcp add graphide --url https://mcp.graphide.com
```

This usually signs in too: it opens the browser, waits, and ends with
`Successfully logged in.` If it ends without signing in (no browser opened,
or `codex mcp list` shows graphide needing a login), run:

```sh
codex mcp login graphide
```

If Codex's sandbox refuses either command, ask the user to approve it. Then
tell the user: "Graphide is connected. Quit Codex, run `codex resume --last`,
and say continue."

### Other agents

Add an MCP server named `graphide`, of type HTTP (Streamable HTTP), at
`https://mcp.graphide.com`, in your client's MCP settings. It signs in with
OAuth (dynamic client registration and PKCE). Each client stores it under
its own keys; https://graphide.com/docs/mcp/ has the exact settings for
Cursor, VS Code, Gemini CLI, Windsurf, Zed, Cline, opencode, Amp, Goose,
JetBrains and the chat apps. If you cannot add it yourself, tell the user
where in their client's settings to add it.

### No browser on this machine

Over ssh, in a container or in a cloud agent, the browser cannot open here.
Tell the user that the sign-in needs their own browser, and ask them to run
these steps in the agent on their own computer.

## 3. Graphide CI: switch the repositories the user picks

Switching a repository opens one pull request that changes each x64 Linux
job's `runs-on` line to `graphide` and nothing else, and merges it if
GitHub's rules allow. From then on those jobs run on Graphide's runners
(the merge is itself a push, so a workflow that runs on push starts there
at once). Jobs Graphide cannot run (macOS, Windows, Arm, or runners of the
user's own) stay where they run, and the pull request lists them. Nothing
changes until the user agrees, no one at Graphide approves anything, and
nothing needs turning on by hand.

First call `ci_status` to see where each repository stands. With no
installations, the GitHub App is not installed yet: step 4's `review_setup`
gives the install link; come back here after it. For each repository:

- `can_switch: true`: it can switch.
- `state: "opened"` with no `merged_at`: its switch pull request waits on
  GitHub (a review or a required check); `ci_switch` offers the merge.
- `state: "opened"` with `merged_at`, or `"live"`: it is on Graphide CI.
  `live` with no `last_job_at` means its workflows already ask for
  `runs-on: graphide` but no run on Graphide is recorded yet: tell the user
  it is set to run on Graphide CI, not that its jobs ran there.
- `state: "left"`: it stays on its own CI, its `message` says why and
  what would change that, and its `link` is the one page that fixes it.
  Tell the user the message as it is, with the link. None of these is a
  lock to get around: whether to change a workflow or a GitHub setting is
  the user's choice, and after a change on the default branch `ci_status`
  gives the new answer within five minutes. The usual ones: a personal
  account (Graphide CI works with GitHub organizations: move the
  repository to a free organization and install Graphide there), no
  workflows, no job that can move as it is (jobs on macOS, Windows or Arm
  stay; a job on a self-hosted or third-party runner moves once its
  `runs-on` is `ubuntu-latest`, if it can run on x64 Linux), or a public
  repository the organization's Default runner group blocks (an owner
  ticks Allow public repositories inside that group).

1. **Ask** which of the switchable repositories to move to Graphide CI,
   with your question tool. Several is fine, and so is none.
2. **Switch** each one the user agreed to: call Graphide's `ci_switch` tool
   if you have it, without `confirm`; put its `ask` to the user, and only
   if they agree call it again with the same `installation_id`, `repo` and
   that `confirm`. Without the tool, ask the user to press **Switch to
   Graphide CI** on its row at https://graphide.com/dashboard/. Never switch
   a repository on your own.
3. **Merge**: follow the answer's `next`. `merged`: done. `blocked`: GitHub
   held the pull request back (a required review or check): give the user
   `pr_url`; once it is approved or its checks pass, call `ci_switch` again
   for that repository, which then offers the merge (or the user presses
   **Merge PR** on the dashboard). `cannot_switch`: tell the user the
   `message`, which names the page that fixes it (often the GitHub App's
   permission request, which an owner accepts).

If `ci_status` lists `setup.steps`, a GitHub owner must click those on
GitHub first: give the user each step's `url`, and do not change the
organization's settings yourself. To hide repositories the user does not
want, they press **Choose repositories** next to the account's name on the
dashboard and leave those out on GitHub.

There is nothing else to choose. If the user asks about speed, tell them
Graphide's team tunes their CI over time, and they see it as faster runs.

## 4. Turn review on

Call `review_setup`. In a git checkout of a GitHub repository, pass it as
`repo` (`owner/name`) so it comes first. The answer has a `step` and a `say`,
and sometimes a `url`, `repos` and an `ask`:

- `install`: GitHub is not connected yet, or not for `repo`. Give the user
  `url`, then call `review_setup` again with `wait: true`; it answers within
  120 seconds of them finishing on GitHub.
- `terms`: give the user `url` to accept Graphide's terms, then call again
  with `wait: true`.
- `choose`: put `ask` to the user with your question tool (AskUserQuestion,
  or your client's own), offering the `repos` as choices; more than one is
  fine.
- `ready`: review is on. Show what `review_status` says.

To turn repositories on, call `review_repos` with `on: ["owner/name", ...]`
and no `confirm`. It changes nothing and answers an `ask` and a `confirm`.
Put the `ask` to the user with your question tool. Only if they agree, call
`review_repos` again with the same `on` and that `confirm`. Never confirm on
your own: the question is how the user agrees to their code being stored.

## 5. Agent signals

Agent signals are on by default. Do not ask the user about them; tell them
what they are in these words:

"Agent signals let your coding agents (Claude Code, Cursor and Codex) tell
Graphide CI when they start work, change dependencies, or are about to push
or merge, so warm machines are waiting when the push lands. They send event
names with the repository, branch and commit, never your code or your
conversations, and they never change whether a job passes. If your agent
asks Graphide to test a commit, that commit is sent for the test."

Then tell them they can turn agent signals off for their organization at
any time, in its Settings at https://graphide.com/dashboard/#agent-signals,
or on one machine with `GRAPHIDE_SIGNALS=off`. Do not add Graphide's hook
files (`.graphide/agent-signal.sh` and the hook settings beside it) to any
repository yourself, and do not push them. Once a repository carries the hook files, Claude
Code asks once to approve the project's `graphide` MCP server, and Codex
runs the project's hooks only after the user trusts them once in `/hooks`.

## What to say at the end

Before saying review is on, check it: `review_status` says `PR review is on`
for each repository. A graph that is ready is not enough.

"Graphide PR review is on for <repositories>. Graphide builds each
repository's graph first, which takes a few minutes; reviews start with the
next pull request. Ask me for Graphide's review status any time, or to change
how a repository is reviewed."

Then say, for each repository the user moved to Graphide CI, whether it
switched (its next push runs on Graphide CI) or waits on GitHub (a review on
its pull request, with its link), and for each that stays, why (its
`message`).

`review_status` shows what is live, the latest reviews with their links, and
why a review is waiting. `review_settings` changes how a repository is
reviewed (every pull request or only when Graphide is mentioned, extra
passes, questions to answer, how many automatic rounds) the same way as
`review_repos`: preview, ask, confirm. `review_findings` gives everything
one pull request's review found, including what it was not sure enough to
post.

## If something fails

- The browser shows "Your account isn't active yet": Graphide's team checks
  some new accounts first. Tell the user to open
  https://graphide.com/welcome, or to write to hello@graphide.com.
- The browser shows "Not available yet": agent setup is closed for now. The
  user can set up reviews at https://graphide.com/dashboard/.
- A tool answers an error: tell the user its message. Do not retry in a loop.
- To undo: `claude mcp remove graphide --scope user` or
  `codex mcp remove graphide`, and uninstall Graphide Review from the
  repositories in GitHub's settings.