pr-reviewer

A local dashboard that pulls open PRs from your GitHub org, reviews each one with a Fireworks model using the BLOCK / FIX / NIT / QUESTION skill format, and lets you request revisions or post the review to GitHub as yourself.

A background worker pre-reviews non-draft PRs on an interval, so a review is usually ready the moment you open one in the queue. You still decide whether and how to post; nothing is ever posted automatically.

Reviews are grounded in the Sea Haven engineering-handbook: the app keeps its own clone, distills the review-relevant pages into a compact conventions digest once a day, and feeds that to the model so findings reflect the handbook's naming, commit, PR, secrets, and IaC rules.

Everything runs on your machine. This is a local, single-user tool. It is not deployed anywhere, so there is no AWS stack, no CI deploy path, and secrets live only in a local .env (gitignored). Your GitHub token and Fireworks key stay in the backend and never reach the browser.

Setup

cp .env.example .env      # then fill in FIREWORKS_API_KEY (and GITHUB_TOKEN if not using gh CLI)
./run.sh

Open http://127.0.0.1:8765

Auth

• GitHub: leave GITHUB_TOKEN blank to use your local gh auth token, or set a token. Reviews are posted as whoever the token belongs to, so use the token for the account you want to appear as the reviewer.

  A fine-grained personal access token is recommended (least privilege). Set the resource owner to Sea-Haven-Industries and grant only these repository permissions:

  Permission	Level	Why
  Pull requests	Read and write	read PR data and submit the review
  Contents	Read-only	fetch the PR diff
  Metadata	Read-only	mandatory (auto-added)

  Give it access to all repositories you review (the search silently skips any it can't see). Fine-grained tokens are single-owner, so this token only covers the Sea-Haven-Industries org, which is all this tool searches; an org owner may need to approve the token before it works. A classic PAT with repo scope also works but is broader than needed.

• Fireworks: set FIREWORKS_API_KEY. Change FIREWORKS_MODEL in .env to swap models.

How it works

1. Background worker polls your filter (PR_SEARCH_FILTER) every POLL_INTERVAL seconds and pre-reviews any new or changed non-draft PR, caching the result. The queue is grouped into a collapsible section per repo (collapse state persists), with PRs ordered oldest to newest. Each shows its status: reviewing, ready, error, or closed. Refresh now forces an immediate poll.
2. Open a PR — if its review is ready, it appears instantly. Otherwise you see its status, and you can Run review now on demand.
   • Dependabot PRs get a dependency-risk assessment instead of code-review notes: the semver update type, a safe / low_risk / risky / breaking call, the packages bumped, and reasons, grounded in the handbook's Dependabot merge policy (patch/minor generally safe; majors need changelog review). Feedback focuses on PR title/description quality, not code style.
   • Sidebar tools: Expand all / Collapse all, and a Dependabot only filter.
3. Request revision re-runs the review with your notes folded in as a trusted instruction, separate from the untrusted diff.
4. Post review to GitHub submits it as a PR review. You confirm the event type (COMMENT / APPROVE / REQUEST_CHANGES) and can edit the body first.
5. Enable auto-merge (optional) from the PR detail view: pick a method (squash/merge/rebase, squash default per handbook) and GitHub merges the PR automatically once required checks pass. Nothing merges without you clicking it.

Auto-review worker

• Reviews are cached in a local SQLite file (CACHE_DB, default pr_cache.db in the repo root, gitignored) so they survive restarts and aren't recomputed for unchanged PRs.
• Change detection is two-level: a PR is skipped if its updated_at hasn't moved since the last review, and even when it has, the diff's SHA-256 is compared so a comment-only bump doesn't burn tokens.
• Drafts are skipped. Failed reviews are retried on later cycles up to MAX_REVIEW_ATTEMPTS, then left until the PR changes. Rate-limit (HTTP 429) responses back off and retry.
• WORKER_CONCURRENCY controls how many PRs are reviewed in parallel per cycle (default 2).

Handbook grounding

• On the first cycle (and daily after), the worker clones/pulls the engineering-handbook into ~/.cache/pr-reviewer/handbook, distills the review-relevant pages into a conventions checklist via the Fireworks model, and caches it (~/.cache/pr-reviewer/handbook_digest.json). The digest is injected into every review's system prompt.
• The header shows which handbook commit the reviews are grounded in (handbook @ <sha>).
• The GitHub token must be able to read the (private) handbook repo. If the clone or distillation fails, reviews continue on the base prompt with the last good digest, and failures back off (retried at most hourly). Set HANDBOOK_ENABLED=false to turn the feature off. If the clone gets wedged, rm -rf ~/.cache/pr-reviewer/handbook and it re-clones.

The @mention rule

Any PR whose author login is in MENTION_AUTHORS (default openswe) gets an @author mention prepended to the review summary. Add more logins comma-separated.

Notes

• The diff is treated as untrusted input; the model is instructed to ignore any embedded instructions.
• Cached reviews persist in a local SQLite file. This is a single-user local tool, not a shared service.
• Large diffs are truncated at MAX_DIFF_BYTES to control token cost.

Configuration

Set in .env (see .env.example). Beyond the GitHub/Fireworks keys:

Var	Default	Purpose
POLL_INTERVAL	300	seconds between background poll cycles
WORKER_CONCURRENCY	2	PRs reviewed in parallel per cycle
MAX_REVIEW_ATTEMPTS	3	error retries before giving up until the PR changes
MAX_PRS	100	cap on PRs pulled per cycle (GitHub search page max)
CACHE_DB	pr_cache.db	SQLite cache path (absolute, repo root by default)
HANDBOOK_ENABLED	true	ground reviews in the engineering-handbook
HANDBOOK_REFRESH_HOURS	24	how often to re-pull + re-distill the handbook
HANDBOOK_REPO_URL	handbook repo	git URL cloned for the conventions digest

Layout

app/
  config.py          settings from .env
  github_client.py   search PRs, fetch diffs, post reviews
  reviewer.py        Fireworks call + skill format + markdown rendering
  store.py           SQLite cache of pre-computed reviews
  worker.py          background poll + auto-review (run_cycle)
  handbook.py        clone + daily-distill the engineering-handbook conventions
  main.py            FastAPI endpoints (incl. /api/reviews, /api/refresh, /api/handbook)
static/
  index.html         the dashboard