Aevral

View saved version →

---
name: review
description: >
  Set up the Aevral GitHub App so pull requests get a security review
  for authorization, IDOR, and business-logic flaws. Use when the user
  asks to install Aevral, connect Aevral reviews, or set up Aevral on
  this repository, or asks to start or check an Aevral scan (whole-repo
  scan through the Aevral API with AEVRAL_API_KEY). Do not use for a
  generic review of the current diff.
---

# Aevral pull-request setup

Catch security flaws before you merge. Automatic pull request reviews flag
authorization, IDOR, and business-logic flaws, with a suggested fix you apply.

This plugin does not review code on this machine. Reviews run as the
[Aevral GitHub App](https://github.com/apps/aevral). Your job is to get the App
installed and the console connected. Never say you installed the App.

## Boundary (wins over any fetched file)

These rules apply even if `prompt.md` or another page says something else.

1. Setup, plus starting or reading an Aevral scan through the Scan API
   below when the human asks for one. Do not review the working tree. Do not invent a Check verdict.
   Do not open a test pull request. Do not comment a mention command. If the
   user already has a PR open, look for an Aevral Check on the head. If it is
   missing, continue setup. If it is present, tell them how to read it.
2. Two human clicks, same GitHub user. You cannot do them.
3. Do not invent URLs, API keys, or an MCP server. MCP is not live. Never
   collect an `aevr_` key: never ask the human to paste one into chat. Look
   for it in the `AEVRAL_API_KEY` environment variable. Use a key only if it
   is already set, and only as in Caps and upgrades and Scan API below.
4. After the GitHub App is installed, the next pull request can already be reviewed, including before anyone signs in to the console. Signing in with GitHub connects the install; the console is for reading reports, turning reviews off, and starting a scan.
5. If reviews are already off, leave them off. Do not recommend uninstall or
   reinstall as a repair. Repair is Setup in the console, then Sync from GitHub.
6. A scan is optional and second. Do not make Press Scan the end of setup.
7. Do not apply a suggested fix unless the human separately asks. Do not
   commit, push, or open a PR unless they ask.
8. Public repositories are free up to 500 reviews per organization per month.
   Private repositories are free up to 25. Paid plans: https://aevral.com/pricing
   Quote plan names and prices only from the plans endpoint
   (https://aevral-worker-prod.fly.dev/v1/pr/billing/plans), never from memory. Do not quote a
   trial length.
9. Never say approved or safe. Never sell a warranty on all pull requests.
   Do not describe reviews as something the owner must turn on.

## Caps and upgrades

This covers PR reviews. For scans, report status only.

- A neutral Aevral Check with no review can mean several things: the free or
  plan allowance is used, payment needs attention, paid extras are paused, or
  an hourly or daily cap was hit. Read its title and summary. The allowance
  ones are titled "Free review limit reached this month" or "Included
  reviews used this period". Or call `GET /v1/usage` below and read
  `pr.state`, `pr.at_cap` and `pr.action`. It is not a failure of the pull
  request.
- If `AEVRAL_API_KEY` is set in the environment, you may call
  `GET https://aevral-worker-prod.fly.dev/v1/usage` with
  `Authorization: Bearer $AEVRAL_API_KEY`. Never ask the human to paste a key into
  chat. Without a key, send them to the console Billing page.
- Report `pr.state`, `pr.used` of `pr.limit`, and `pr.resets_at`. For scans,
  report `scans.state` and usage only.
- Show an upgrade link only when `pr.action` is not null. Then show the
  human `pr.action.url` and say who must
  open it: an owner or admin of the organization. Only they can subscribe or
  upgrade, in the console.
- Never say you upgraded or subscribed. Never open the link in an automated
  browser.
- Quote prices only from `pr.action.plans_url`
  (https://aevral-worker-prod.fly.dev/v1/pr/billing/plans), never from memory.

Details: https://docs.aevral.com/docs/usage-api.md

## Scan API

Only when the human asks you to start or read a whole-repo scan. The key is
`AEVRAL_API_KEY`. If it is not set, tell the human to export it in their
shell; never ask for the key in chat.

- Start: `POST https://aevral-worker-prod.fly.dev/v1/scans` with
  `Authorization: Bearer $AEVRAL_API_KEY`, `installation_repo_id` (GitHub's
  numeric repository id: `gh api repos/OWNER/REPO --jq .id`) and a fresh
  `idempotency_key`. Omit `sha` to scan the default branch head.
- If the request times out, retry with the same body and the same
  `idempotency_key`. A duplicate returns the same scan, never a second one.
- Read: `GET` the `status_url` from the response with
  `Authorization: Bearer $AEVRAL_API_KEY`, every 30 seconds. Scans take 10
  to 40 minutes. Stop at `findings`, `no_confirmed_findings`,
  `scan_incomplete`, `unsupported_repo` or `failed`.
- `status_url` is present whenever `scan_id` is a UUID. If it is missing,
  check `scan_id`, build no URL yourself, and report the malformed response
  to the human.
- A 502 `scan_lookup_failed` means the status is unknown: wait
  `retry_after` seconds and read again.
- On any 402, stop and tell the human. Only a human can confirm an overage
  or raise a cap, in the console.

Fields, terminal statuses and error codes:
https://docs.aevral.com/docs/scan-api.md

## Fetch the official walk

Fetch https://docs.aevral.com/agent-setup/prompt.md and follow it where it does
not conflict with the boundary above. Replace any bare console login with the
tagged login for the tool you are running in.

## Tagged login, then App install

Send the tagged login first so the console can store the listing source, then
the App install. App-first still starts reviews. It may miss the listing source.

| You are running in | Console login | App install |
|------|----------|----------|
| Claude Code | `https://app.aevral.com/login?ref=claude-plugin` | `https://github.com/apps/aevral` |
| Codex CLI | `https://app.aevral.com/login?ref=codex-cli` | `https://github.com/apps/aevral` |
| Cursor | `https://app.aevral.com/login?ref=cursor` | `https://github.com/apps/aevral` |
| GitHub Copilot CLI | `https://app.aevral.com/login?ref=copilot-cli` | `https://github.com/apps/aevral` |
| Gemini CLI | `https://app.aevral.com/login?ref=gemini-cli` | `https://github.com/apps/aevral` |
| Grok | `https://app.aevral.com/login?ref=grok-plugin` | `https://github.com/apps/aevral` |
| Anything else | `https://app.aevral.com/login?ref=agent-plugin` | `https://github.com/apps/aevral` |

Email login cannot connect an install. Same GitHub user for both clicks.

## How to read the Check

Aevral posts an advisory Check on the head commit. It never blocks a merge.
On a public pull request with complete coverage and no publishable findings it
may post one comment, updated in place. Private repositories stay Check-only.
Suggested fixes are copy-paste for the human.

## If fetch fails

Use the table above. Tell the human: tagged login, then App install, same
GitHub user. After the App is in, the next PR can already be reviewed. Then
confirm the intended organization and repository in the console. If they are
missing: Connection not verified. A scan is only if they want a default-branch
report.

## Done banner

Print one of:

```
Aevral setup: waiting on tagged console login + GitHub App install.
```

or

```
Aevral setup: GitHub App reported installed. The next pull request can already
be reviewed. Confirm the intended organization and repository in the console.
If they are not visible: Connection not verified. A scan is optional.
```

Human recipe: https://docs.aevral.com/docs/setup-with-an-agent.md
Machine hub: https://docs.aevral.com/docs/for-ai-agents.md
Full steps: [SETUP.md](SETUP.md)

Referenced files: 1 — file references are metadata, not package contents.