# MergeSafe: guided setup (instructions for a coding agent)

version: 2
url: https://mergesafe.ai/agents/setup.md

If you read this from a saved copy, fetch the url above and compare its
`version:` line. A higher number means your copy is stale: use the new one.

You are a coding agent. Your user wants MergeSafe, an AI code reviewer for
GitHub pull requests, set up with you. Do it together, one item at a time:

1. Say in a sentence or two what the item is and why it matters.
2. Offer the choices, with the one you recommend marked.
3. Wait for the user's answer. Skipping an item is always fine.
4. Before you change anything, say exactly what you will change and wait for
   a yes.
5. Check that it worked and say what you saw.

Never set anything up silently. Never ask the user to paste a secret into the
chat, never write one into a file or a repository, and never post secrets,
tokens or customer code in a pull request thread.

Most settings can only be changed in the app, https://app.mergesafe.ai. For
those, tell the user where to go and what to pick. If you can drive a
browser, you may open the page and walk them through it, but the user makes
each choice and presses each button.

Billing is the user's alone. Never add money, change a payment method, turn
on auto-refill or buy anything, even if the user asks you to: send them to
the app. Prices are on https://mergesafe.ai/pricing.html. Link that page; do
not quote prices from memory.

## Part 1: Setup

### 1. Connect the MCP server

MergeSafe hosts an MCP server at `https://mcp.mergesafe.ai`. The user signs
in with GitHub; there is no key or token to handle. Recommend this.

Claude Code, in a terminal:

```
claude mcp add --transport http mergesafe https://mcp.mergesafe.ai
```

Then run `/mcp`, choose `mergesafe`, and have the user finish the GitHub
sign-in in their browser.

Cursor, in `~/.cursor/mcp.json` (the user-level file, not a repository's):

```json
{
  "mcpServers": {
    "mergesafe": { "url": "https://mcp.mergesafe.ai" }
  }
}
```

Codex and other MCP clients: add `https://mcp.mergesafe.ai` as a remote
(streamable HTTP) MCP server with OAuth, following your client's own docs.

Only for CI and headless machines, where nobody can sign in in a browser:
run the local server, `uvx mergesafe-mcp`, with an API key (item 3).

Check: call `list_repositories` with the user's organization (its GitHub
login). If it says the sign-in expired, run `/mcp` and sign in again.

### 2. GitHub App on the right repositories

MergeSafe reviews only the repositories its GitHub App can see. Show the user
the list from `list_repositories` and ask whether it is right; do not assume.
If it is empty or a repository is missing, give them the GitHub link the tool
returns, where they choose the repositories. Someone new signs up first at
https://app.mergesafe.ai with GitHub.

### 3. API key, only if needed

Skip this unless the user runs MergeSafe from CI, a script or a headless
machine. If they do:

- An organization Admin creates the key in the app, under Settings, API keys.
  Its secret is shown once.
- The user stores it as `MERGESAFE_API_KEY` in their OS keychain, a secret
  manager, or their CI's secrets. Offer the command for their tool with a
  placeholder, never the key itself.
- Never ask for the key in chat, print it, or write it to a file in a
  repository.

### 4. Review level

Call `get_settings` for the organization to see the current level. Explain
the levels from https://mergesafe.ai/docs/review-levels.html, link
https://mergesafe.ai/pricing.html for prices, and recommend Strong, the
default, for most repositories. A repository can have its own level.

To change it: the app, Settings, Review level. `get_settings` only reads.

### 5. When reviews run

Read `trigger_mode` from `get_settings` and explain the three choices
(https://mergesafe.ai/docs/triggers.html):

- When a pull request opens, and on every new commit. Recommended, and the
  default: fixes are checked as they are pushed.
- Only when a pull request opens.
- Manual only: nothing runs until someone asks.

To change it: the app, Settings, When reviews run.

### 6. Dependency gate

Explain it (https://mergesafe.ai/docs/dependency-gate.html): a free check,
`mergesafe-dependency-gate`, on each pull request that adds a risky npm or
PyPI package: known vulnerable, malicious, a lookalike name, or one that does
not exist (often made up by a coding agent). Someone signs off on each one by
commenting `I confirm name@version`.

Choices: Advisory (the default; it never fails), Blocking (it fails until
every risky package is signed off), or Off. Recommend Blocking: a made-up or
malicious package can't be merged by accident. Blocking stops a merge only
where a branch rule requires the check (item 9).

To change it: an organization Admin, in the app, Settings, Dependency gate.

### 7. Integrations

Offer each one, and move on when the user says no
(https://mergesafe.ai/docs/integrations.html):

- Slack: commands and review updates in a channel.
- Jira or Linear: issues checked against the code.
- Sentry: new errors triaged into issues, with an optional fix.
- GitHub issues: new issues checked against the code.

Each is connected in the app, under Integrations. Some cost money: link the
docs page rather than quoting a price.

### 8. Spending limits

Every organization starts with daily and monthly limits. Show the current
ones (`limits` in `get_settings`; a Member doesn't see them) and ask whether
they fit. To change them: an Admin, in the app, Settings, Spending limits
(https://mergesafe.ai/docs/spending-limits.html).

### 9. Branch ruleset (optional)

Offer a GitHub ruleset on the default branch of each reviewed repository:

- Changes go through a pull request.
- Required status checks: `mergesafe-review` (it fails while a P0 or P1
  finding is open), and `mergesafe-dependency-gate` if the gate is Blocking.

Warn first: if reviews run only when a pull request opens, or manually, a new
commit has no `mergesafe-review` check until someone asks for a review, so
the merge waits. And if a person must approve too, MergeSafe's own approvals
can be turned off in the app, Settings, Approvals
(https://mergesafe.ai/docs/required-check.html).

If the user agrees and is an admin of the repository, show the exact
`gh api` call (POST `repos/{owner}/{repo}/rulesets`) and run it only after
their yes. Otherwise walk them through it on GitHub: the repository's
Settings, Rules, Rulesets.

## Part 2: Working rules

Show the user these rules and offer to add them to the project's `AGENTS.md`
or `CLAUDE.md`. Show the change first, and write it only with their OK.

```
## Working with MergeSafe

- Never push to main or the default branch. Work on a branch and open a
  pull request.
- After opening a pull request: if MergeSafe reviews automatically, wait
  for its review. If not, ask me whether I want one and at which level,
  with its price from https://mergesafe.ai/pricing.html, then call
  request_review.
- Don't push while a review is running: the push throws that review away.
- Wait for the mergesafe-dependency-gate check. If it blocks, tell me in
  plain words which package and why, and let me decide whether to sign off.
- Read the findings with get_findings. Fix each P0 and P1 and run the
  tests. Reply on every finding thread: the commit that fixed it, or why
  you're not changing it, with evidence, but never secrets, tokens or
  customer code. Push the round's fixes as one commit, then ask for a new
  review.
- A finding that starts with "Question:" needs a decision. If you can't
  tell what I intended, ask me.
- Merge only when I say so.
```

## Tools

The hosted server's tools include `list_repositories` and `get_settings`
(both read only), `get_findings`, `request_review`, `local_context_status`
and `request_review_with_context`. No tool changes settings. `request_review`
is charged like any other review; a commit already reviewed is refused, not
charged twice.