# Set up the PR bot (for agents)

The runbook a coding agent follows to put the Repowise PR bot on a GitHub repository, from sign-in to a verified review. Each step names who does it, the exact command or link, the sentence for the person, and how to check it.

You are a coding agent setting up the Repowise PR bot on the user's GitHub
repository. The bot is a GitHub App, `repowise-bot`, that reviews every pull
request against the whole repository: one comment, a `Repowise review` check
on every push, and threads on the lines that need them. Free checks run on
public repositories. AI review comes with Pro or Teams.

A person pastes this prompt to start you:

```text
Set up the Repowise PR bot on this repository. Follow https://docs.repowise.dev/hosted/bot-setup.md step by step. Tell me the exact link to click when a step needs me (installing the GitHub App, or a plan for a private repo), and ask me before anything that costs money. Finish by checking that the Repowise review check ran on a pull request.
```

What the bot does and every setting it takes: [PR bot](https://docs.repowise.dev/hosted/bot.md).
Setting up all of Repowise Hosted (index, MCP, bot):
[hosted setup runbook](https://docs.repowise.dev/hosted/setup.md).

## Rules

- Ask the person before anything that costs money: a plan, a trial, adding
  credits, turning AI review on, or raising an AI spend cap. Never start a
  checkout, trial or plan change yourself.
- Never install a GitHub App or approve an install. Hand the person the link.
- Never ask the person to paste a key or token into this conversation. Never
  print, echo or log one. Refer to a key by its environment variable name.
- Batch everything the person has to do into one message, with every link in
  it.
- Every step is safe to run again. Skip a step that is already done.
- Run commands from the repository root. The bot works on GitHub repositories
  only.

## Steps at a glance

| # | Step | Who |
|---|---|---|
| 1 | Check the CLI and sign in | Agent, the person approves once |
| 2 | Read the state | Agent |
| 3 | Install the GitHub App | Person |
| 4 | Confirm an organization install | Person (organization admin) |
| 5 | Turn reviews on | Agent |
| 6 | Plan for a private repo or AI review | Person |
| 7 | AI review settings (optional) | Agent |
| 8 | Coverage (optional) | Agent, the person merges |
| 9 | `.repowise/bot.yaml` (optional) | Agent, the person merges |
| 10 | Verify on a pull request | Agent |

## 1. Check the CLI and sign in

**Who:** agent. The person approves the sign-in once.

```bash
git remote get-url origin   # github.com/<owner>/<name>
repowise --version          # needs 0.61 or newer
```

No CLI, or older than 0.61: install or upgrade it with the first tool on PATH
(`uv tool install repowise`, `pipx install repowise`, or
`python3 -m pip install -U repowise`).

```bash
repowise login            # opens a browser
repowise login --device   # no browser on this machine: prints a URL and a code
```

**Tell the person:** "A browser tab will open to sign in to Repowise. Approve
it and come back." With `--device`, relay the URL and code it prints.

No browser tab within about 30 seconds (SSH, a container, a cloud agent):
stop `repowise login` and run `repowise login --device` instead.

**Check:** `repowise hosted status --format json` returns
`"account": {"signed_in": true, ...}`.

**Write access.** `repowise login` asks for read and write, which the steps
below need. A sign-in made with a read-only API key
(`repowise login --with-token`) can read the state but gets `forbidden` (HTTP 403) on
`reviews on`. Do not use `--with-token`: the key would pass through you.

## 2. Read the state

**Who:** agent. Read-only, run it as often as you like.

```bash
repowise hosted status --repo <owner>/<name> --format json
```

The fields this runbook uses:

| Field | Meaning |
|---|---|
| `account.signed_in` | `false`: go to step 1 |
| `effective_tier` | `free`, `pro`, `teams` or another paid tier |
| `repo.private` | Private repos need a paid plan for reviews |
| `repo.indexed`, `repo.status` | The hosted index: `ready`, `queued`, `scanning` or `failed` |
| `bot.installed` | The App covers this repo |
| `bot.unclaimed` | Installed, but not linked to a Repowise account yet (step 4) |
| `bot.enabled` | Reviews are on for this repo |
| `bot.install_url` | The install link for this account |
| `coverage.state` | `none`, `pr_open` or `reporting` |
| `bot.code` | One code for the bot on this repo: `not_installed`, `pending_admin`, `needs_github`, `needs_claim`, `other_owner`, `needs_plan`, `ready_to_enable`, `on`, or `unknown` (read again in a minute) |
| `bot.claim_url` | Where the person confirms an install that is `needs_claim` (step 4) |
| `bot.ai.code` | AI review: `ai_on`, `ai_off`, `needs_claim`, `needs_plan`, `ai_paused_credit`, `ai_paused_cap` or `unknown` |
| `bot.ai.mode`, `bot.ai.mode_source` | The review mode in force (`signals` or `ai`) and the layer that set it: `default`, `org`, `repo` or `org_locked` |
| `bot.ai.depth`, `bot.ai.depth_source` | The repo's review depth (`light`, `auto` or `deep`) and the layer that set it, same values |
| `bot.ai.depth_locked` | `true`: the organization policy locks the depth; per-PR labels are ignored, `/repowise review deep` still runs one deep review |
| `bot.last_review` | The newest review on this repo: `pr_number`, `status`, `tier` (`signals` or `ai`), `check_url` |
| `next_action`, `action_url`, `next_who` | The one thing to do next, the link for it, and who does it (`agent` or `human`) |
| `coverage.state` | `none`, `pr_open` or `reporting` |
| `steps[]` | Each open step: `id` (`bot`, `coverage`, ...), `code`, `done`, `who` (`agent` or `human`), `action`, `url`, `repo_id` |

**Follow `next_who`.** When it is `human`, send the person `next_action` and
`action_url` as they are, then wait and read the state again. When it is
`agent`, do the step this runbook gives for that code. If the payload has no
`next_action`, use the first entry in `steps` whose `done` is `false`, with its
`who`, `action` and `url`.

The bot's `repo_id` for API calls is the `repo_id` on the `bot` or `coverage`
step.

Do not read `complete` as "the bot is set up": the bot and coverage steps can
be optional and leave `complete` true while reviews are off. Read
`bot.enabled` and the `bot` step instead.

An `error` field means the read failed: `signed_out` (step 1), `offline`
(retry once after a minute), `unsupported` or `http_<code>` (report it).

## 3. Install the GitHub App

**Who:** person. Skip when `bot.installed` is `true`.

When `<owner>` is an organization, ask first: "Are you an owner of `<owner>`
on GitHub?" The answer picks the sentence below and decides whether step 4
waits on someone else.

**Tell the person:** "Open https://repowise.dev/bot/install?src=agent. On
GitHub, pick the account or organization that owns `<owner>/<name>`, select
that repository (or All repositories), and click Install. If you already use
Repowise, GitHub shows this as a second app: repowise-bot reviews pull
requests, and repowise-app only reads code to index it. Tell me when you are
done."

**Check:** run step 2 once a minute, up to 10 times, until `bot.installed` is
`true`.

- A personal install links to the person's Repowise account when they sign in
  with the same GitHub account. Nothing else to click.
- The person is not an owner of the organization: their install becomes a
  request that an owner approves on GitHub. The `bot` step reads "Waiting for
  an organization admin to approve the PR bot install." Tell the person: "GitHub
  sent the install request to the owners of `<org>`. Forward this to one of
  them: Please approve the Repowise PR bot for `<org>/<name>`. Open
  https://repowise.dev/bot/install?src=agent (or approve the pending request
  under the organization's Settings, GitHub Apps), then open
  https://repowise.dev/settings/bot and click Claim (org admin)."
- A request still unapproved after the 10 polls is not a failure. Stop, send
  the "Waiting on you" report with both links, and resume at step 2 when the
  person says it is approved.
- The `bot` step says "Sign in with GitHub so Repowise can link the PR bot.":
  tell the person "Open https://repowise.dev/settings?tab=github and connect
  your GitHub account."
- `bot.installed` still `false` after the person says done: ask them to open
  https://repowise.dev/settings/bot while signed in and confirm the repository
  is listed there.

The default branch is indexed after the install, which takes 3 to 10 minutes
per repository. Right after the install the bot also reviews the most recently
updated open pull request on up to three of the new repositories, with the free
checks only. On a private repository with no paid plan behind it, no review
runs: the `Repowise review` check reads `Not reviewed: <reason>` until step 6
is done.

## 4. Confirm an organization install

**Who:** person, an admin of the organization. Only when `bot.code` is
`needs_claim` (or `bot.unclaimed` is `true`). When the payload has
`bot.claim_url`, send that link: it opens the confirm page for this install.

**Tell the person:** "The PR bot is installed on `<org>` but not linked to
Repowise yet. An admin of `<org>` opens https://repowise.dev/settings/bot and
clicks Claim (org admin), or opens the page GitHub returned to after the
install, `https://repowise.dev/bot/installed?installation_id=<id>`, and clicks
Confirm organization access. GitHub may first ask them to allow organization
access, which reads organization membership only."

`<id>` is the number GitHub put in that return URL, also the last part of
`https://github.com/organizations/<org>/settings/installations/<id>`. When you
do not have it, give the settings link only.

**Check:** step 2 shows `bot.unclaimed` `false`, and the `bot` step's `who` is
`agent`.

Until the install is claimed, the bot runs the free checks on public
repositories, and AI review does not run.

## 5. Turn reviews on

**Who:** agent. Skip when `bot.enabled` is `true`.

```bash
repowise hosted reviews on --repo <owner>/<name> --format json
```

It calls `PATCH /github-app/bot-repos/<repo_id>/enabled` with the CLI's stored
sign-in. Success prints `{"ok": true, "repo": ..., "repo_id": ..., "result": ...}`.
A refusal prints `"ok": false` with an `error` and a `message`, and exits 1:

| `error` | HTTP | What you do |
|---|---|---|
| `not_installed` | 404 | `bot.installed` `false`: step 3. `bot.installed` `true` and `bot.unclaimed` `true`: the install is not confirmed yet, go to step 4 |
| `needs_plan` | 402 | Private repo below a paid plan: step 6 |
| `forbidden` | 403 | The sign-in cannot change settings. Tell the person to run `repowise logout`, then `repowise login`. Retry once after |
| `permission_needed` | 409 | Pass the `message` and the link in its `card` to the person |
| `pending` | 502 or 504 | The bot did not answer in time: run it once more after a minute |
| `signed_out` | 401 | Step 1, then retry |
| `offline` | none | Retry once after a minute, then report |
| `unsupported` | 404 or 405 | An older server: tell the person to turn reviews on at https://repowise.dev/settings/bot |
| `http_<code>` | other | Report the `message`; do not retry |

**Check:** step 2 shows `bot.enabled` `true` and the `bot` step reads "PR
reviews are on."

## 6. Plan for a private repo or AI review

**Who:** person. Ask before anything that costs money.

- Private repository on the Free plan (`needs_plan`, or `repo.private` with
  `effective_tier` `free`). **Tell the person:** "Private repositories need a
  plan. Start Pro here: https://repowise.dev/try-pro?src=agent"
- Public repository, and the person wants AI review on a Free plan. **Tell the
  person:** "The free checks already run on this public repository. AI review
  needs Pro or Teams. Start Pro here: https://repowise.dev/try-pro?src=agent"

Quote only the terms the page shows. Do not start a trial, a starter or a
checkout yourself.

**Check:** run step 2 every 30 seconds, up to 5 minutes, until
`effective_tier` is not `free`. Then run step 5 again. Still `free` after 5
minutes: send the "Waiting on you" report and resume when the person says the
plan is active.

**Right after the plan starts,** AI review turns on by default for a claimed
install and starts spending credit. **Tell the person:** "AI review is on by
default for this repository: about 15 cents of credit per reviewed pull
request, and up to $10 per repository per month by default. Keep it, or switch
this repository to the free checks?" To switch it off, set `review_mode` to
`signals` in step 7, or the person picks Signals at
https://repowise.dev/settings/bot.

**Cost.** AI review uses about 15 cents of credit per reviewed pull request,
so $5 of credit covers about 33 reviews. Pro includes $5 of credit a month.
Each repository has a monthly AI spend cap, $10 by default
(`ai_monthly_cap_cents`: 1000), and each pull request a cap of 60 cents. When
credit runs out, the bot falls back to a light review and says so on the pull
request: "Light review: AI credit ran out. Add credits for the full review."
When the repository reaches its monthly limit instead, the pull request reads
"Light review: this repository reached its monthly AI limit." The owner raises
the limit in the bot settings; adding credits does not lift it.

## 7. AI review settings (optional)

**Who:** agent, only when the person asks for a setting other than the
default, or says no to AI review in step 6.

AI review is on by default for a repository whose install is claimed by an
account on a paid plan, or shared into a paying team, when nobody has picked a
mode. Mode, depth and caps are set on the dashboard
(https://repowise.dev/settings/bot) or through the API below. They are not
read from `.repowise/bot.yaml`. The CLI has no command for them.

The simplest path is the dashboard. **Tell the person:** "Open
https://repowise.dev/settings/bot, pick `<owner>/<name>` and choose AI review
(or the free checks)." Then read the state again: `bot.ai.code` reads `ai_on`
once AI review runs. Use the API below only when the person prefers to give
you a key.

**The key.** The API takes a Repowise API key in `REPOWISE_API_KEY`, which
the person sets in your shell themselves. **Tell the person:** "Open
https://repowise.dev/settings?tab=editor (Coding agents), click New key, tick write, and set
the key as the environment variable `REPOWISE_API_KEY` in the shell I run in.
Do not paste it here." Check it without printing it:
`[ -n "$REPOWISE_API_KEY" ] && echo set` (PowerShell:
`if ($env:REPOWISE_API_KEY) { "set" }`).

**Read the settings in force:**

```bash
curl -sS https://api.repowise.dev/github-app/bot-repos/<repo_id>/config/effective \
  -H "Authorization: Bearer $REPOWISE_API_KEY"
```

It returns `config`, where every key is `{"value": ..., "source": ...}` and
`source` is `default`, `org`, `repo` or `org_locked`, plus `can_edit` and
`locked_keys`. `config.review_mode.value` is `ai` when AI review runs.

**Change them** (ask the person first when the change turns AI review on or
raises a cap):

```bash
curl -sS -X PATCH https://api.repowise.dev/github-app/bot-repos/<repo_id>/config \
  -H "Authorization: Bearer $REPOWISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"review_mode": "ai", "review_depth": "deep", "ai_monthly_cap_cents": 1000}}'
```

Free checks only, no AI spend:

```bash
curl -sS -X PATCH https://api.repowise.dev/github-app/bot-repos/<repo_id>/config \
  -H "Authorization: Bearer $REPOWISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"review_mode": "signals"}}'
```

Send only the keys to change. `{"clear": ["ai_monthly_cap_cents"]}` returns a
key to the org or default value.

| Key | Values |
|---|---|
| `review_mode` | `signals` (free checks, no model) or `ai` |
| `review_depth` | `light`, `auto` or `deep` |
| `ai_monthly_cap_cents` | Whole cents per repository per month, up to 200000. Default 1000 ($10). `0` turns AI review off |
| `ai_pr_cap_cents` | Whole cents per pull request (default 60) |
| `review_sensitivity` | `quiet`, `balanced` (default) or `thorough`: how many points a review posts, at most 3, 5 or 10 |

Every other key is in the [PR bot keys table](https://docs.repowise.dev/hosted/bot.md#keys).

| HTTP | Meaning | What you do |
|---|---|---|
| 200 | Saved | Read the effective settings to confirm |
| 400 | `code` is `bot_config_invalid` (a key or value is wrong), `bot_config_empty` (nothing to change) or `bot_config_conflict` (the same key in `config` and `clear`); `key` names the key and `message` says why | Fix the payload |
| 401 | Key missing or revoked | Ask the person to set `REPOWISE_API_KEY` again |
| 402 | `pr_bot_ai_requires_paid`: AI review needs a paid plan | Step 6. Both 402s, this one and `needs_plan` from step 5, mean a plan |
| 403 | The key has no write scope | Ask the person for a key with write ticked |
| 404 | The repo is not covered by an install this account claimed | Steps 3 and 4 |
| 422 | `bot_config_locked`: the organization's bot policy locks the key | Tell the person an organization admin changes the policy at https://repowise.dev/settings/bot |
| 429 | Rate limited (30 changes a minute) | Wait a minute |

### Review depth

`review_depth` sets how much review each pull request gets:

| Depth | Runs | Credit |
|---|---|---|
| `light` | A light review on every push: one quick pass. Never the deep review | A fraction of deep |
| `auto` | A light review, plus one deep review when the change is risky | A fraction of deep |
| `deep` | The default. A deep review on every push | About 15 cents a pull request |

Set the repository default (ask the person first when it raises spend):

```bash
curl -sS -X PATCH https://api.repowise.dev/github-app/bot-repos/<repo_id>/config \
  -H "Authorization: Bearer $REPOWISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"review_depth": "deep"}}'
```

**Check:** step 2 shows `bot.ai.depth` and `bot.ai.depth_source` `repo`.

What the bot does when a limit is reached:

| Limit | Pull requests get |
|---|---|
| Credit runs out | A light review, whatever depth is set, until credit is added. Signals only, no AI, once Repowise's light-review reserve is used |
| Monthly limit (`ai_monthly_cap_cents`) | The same light review until the limit is raised or next month |
| Per-PR limit (`ai_pr_cap_cents`) | Signals only, no AI, on that pull request's later pushes |

### One pull request at a different depth

A label on a pull request overrides the repository depth for that pull
request:

| Label | That pull request gets |
|---|---|
| `repowise: deep` | Deep review |
| `repowise: light` | Light review |
| `repowise: off` | Signals only, no AI |

The bot reads these labels and never creates or adds them. Create a label once
per repository, then add it (a deep review spends credit, about 15 cents: ask
the person first):

```bash
gh label create "repowise: deep" --description "Repowise: run the deep AI review on this PR" --color 5319E7 --force
gh pr edit <N> --add-label "repowise: deep"
```

A person types the label in GitHub's label picker, which offers to create it.
Adding `repowise: deep` or `repowise: light` runs the review again on the
current commit. Labels take effect when the repository runs AI review;
`repowise: off` works in any mode. For one deep review without a label,
comment `/repowise review deep`
(`gh pr comment <N> --body "/repowise review deep"`). After a quick review,
the `Repowise review` check has a Run deep review button and the bot's comment
a "Run the deep review" checkbox.

**Which depth wins,** highest first:

1. A label on the pull request
2. `/repowise review deep`, for that one review
3. The repository setting (dashboard or API)
4. The organization policy
5. The default, `deep`

A depth the organization policy locks (`bot.ai.depth_locked` `true`) wins over
the labels: the bot ignores them. A `/repowise review deep` comment still runs
one deep review; the check's Run deep review button and the comment's checkbox
are not offered then. `.repowise/bot.yaml` cannot set the depth or the mode.

**Check what ran.** Read the JSON status in the `Repowise review` check on the
pull request's head commit (this works for pull requests from forks too):

```bash
SHA=$(gh pr view <N> --json headRefOid -q .headRefOid)
gh api "repos/<owner>/<name>/commits/$SHA/check-runs?check_name=Repowise%20review&filter=latest" \
  --jq '.check_runs[0].output.text'
```

| Field | Says |
|---|---|
| `tier` | What ran: `t3` deep review, `t1` or `t2` quick review, `t0` free checks |
| `ai` | AI review on this commit: `full`, `light` (the credit or limit fallback), `paused`, `off` or `signals` |
| `effort.depth`, `effort.source` | The depth asked for and where it came from: `label`, `command`, `repo`, `org`, `org_locked` or `default` |
| `effort.label` | The effort label on the pull request, when there is one |
| `effort.ignored` | Why a label had no effect, for example the organization locks the depth; `null` when it applied |

## 8. Coverage (optional)

**Who:** agent opens the pull request, the person merges it. Skip when
`coverage.state` is `reporting`, or a workflow already uploads to
`https://api.repowise.dev/ci/coverage`.

```bash
repowise hosted coverage-pr --repo <owner>/<name> --format json
```

The bot opens a draft pull request that adds the coverage upload to GitHub
Actions. The errors are the same as in step 5. `permission_needed` means the
bot needs Contents and Workflows write on GitHub: pass the `message` and the
`card` link to the person.

**Tell the person:** "Repowise opened a draft pull request that uploads test
coverage from CI: `<coverage.setup_pr_url>`. Review it, mark it ready and merge
it."

**Check:** step 2 shows `coverage.state` move from `pr_open` to `reporting`
after the next CI run on the default branch.

No GitHub Actions, or the bot cannot open the pull request: follow the
coverage part of the [hosted setup runbook](https://docs.repowise.dev/hosted/setup.md)
and [coverage setup](https://docs.repowise.dev/hosted/bot.md#coverage-setup).

## 9. `.repowise/bot.yaml` (optional)

**Who:** agent writes it in a pull request, the person merges it.

- Gate keys (`enabled`, `health_gate`, `check_runs`, `coverage_fail_under`,
  `security_fail_on`, `not_evaluated`, `review_check`, `feedback_decisions`,
  `ignore_paths`, `apply_labels`) are read from the base branch only. A gate
  added in a pull request applies to the pull requests opened after it merges,
  not to the pull request that adds it.
- Comment and presentation keys can come from the pull request's own branch.
- `review_mode`, `review_depth`, `ai_monthly_cap_cents` and `ai_pr_cap_cents`
  are never read from the file: use step 7.

Keys and examples: [configuration](https://docs.repowise.dev/hosted/bot.md#configuration).

## 10. Verify on a pull request

**Who:** agent.

Wait until `repo.status` is `ready` (3 to 10 minutes after the install). Then
use an open pull request opened by a person, or open a small one. The bot
skips pull requests opened by bots and titles with `[skip repowise]`: when
those are the only open ones, open a small one yourself. When AI review is on,
every reviewed pull request spends credit (about 15 cents), a test one
included: ask the person before opening one.

```bash
gh pr checks <N> --watch
```

The check is named `Repowise review`. Read its title:

```bash
gh api repos/<owner>/<name>/commits/$(gh pr view <N> --json headRefOid -q .headRefOid)/check-runs \
  --jq '.check_runs[] | select(.name == "Repowise review") | {status, conclusion, title: .output.title}'
```

- Read the conclusion and the title together. A title that starts with
  `Not reviewed:` means setup is not finished, whatever the conclusion: the
  reason names what is missing (a plan, an unconfirmed install, a skipped pull
  request). Fix it, then recheck.
- Any other finished check: the bot reviewed the pull request.
- With the free checks only, a clean pull request gets no comment. The check
  still reports it.
- No check after 10 minutes: run step 2 and fix what it shows. Then comment
  `/repowise recheck` on the pull request:
  `gh pr comment <N> --body "/repowise recheck"`. The commenter needs write
  access to the repository.
- Pull requests opened by bots, and titles with `[skip repowise]`, are skipped
  and the check says so.

## Done when

- [ ] `account.signed_in` is `true`
- [ ] `bot.installed` is `true` and `bot.unclaimed` is `false`
- [ ] `bot.enabled` is `true`
- [ ] A private repository has a paid plan behind it (`needs_plan` gone)
- [ ] AI review is on (`config.review_mode.value` is `ai`) when the person asked for it
- [ ] Coverage `reporting`, or the coverage pull request handed to the person (optional)
- [ ] The `Repowise review` check finished on a pull request, with a title that does not start with `Not reviewed:`

## Report

```text
The Repowise PR bot is set up on <owner>/<name>.

Done:
- <install, claim, reviews on, AI review and its cap, coverage, the check on PR #<N>>

Waiting on you:
- <each person step, with its exact link>
```
