Install

Desktop app (one person)

You get the queue, the drafted review and the Post button in a window on your Mac or Linux laptop, and the same app on your phone. One command:

npx reviewstage

You need Node 20 or newer, Git and Claude Code; the app brings its own server and fetches gh, jq and cloudflared once, pinned by checksum. No Docker, no .env, no service token.

A window opens and walks you through three steps:

1. Continue with GitHub — a short code at github.com/login/device.
2. Connect Claude — your own account; reviews bill to your plan.
3. Pick repositories — the ones you review. Change them any time on the Repositories page in the sidebar.

first launch · three steps

The three wizard steps in the desktop app: Continue with GitHub, Connect Claude, then a searchable list of repositories with a Start reviewing button.

Then your queue. The dock badge counts review requests; a notification fires when it rises.

Your phone. In the app, Settings → Your phone → Enable phone access opens a secure tunnel to your laptop and shows a QR code on the card (the app menu has the same, Enable phone access…, in a window of its own). Scan it with the camera: the phone is signed in as you, no second GitHub login. Share → Add to Home Screen, open it from there, and turn on Settings → Push → This device. The code is single-use and valid for 30 minutes; New code mints a new one.

phone access · QR

The desktop app's phone window: a QR code, the tunnel address under it, and the line 'Scanning signs you in as octocat. Code valid until 14:32 — reopen this window for a new one.'

What if my Wi-Fi drops? The tunnel reconnects by itself after a dropped connection or sleep, and the address stays the same for as long as the app runs. Quitting the app ends it; the next Enable phone access gets a new address, so scan again.

Switch GitHub account is in the account ⋯ menu. Everything lives under ~/.reviewstage; delete it to start over. Posting is live from the first run: the Post button is the gate. More in the FAQ and INSTALL-DESKTOP.md.

Team (Docker Compose)

You get one server for the whole team; everyone signs in as themselves, and one install reviews many repositories. Three commands:

git clone https://github.com/Wimukti/reviewstage && cd reviewstage
cp .env.example .env
docker compose up -d

You need Docker with Compose v2, a host with 2 GB of RAM and 3 GB of free disk, and a Claude Pro, Max, Team or Enterprise plan for everyone who runs reviews.

Set two values in .env before up:

Key	What
REPOS	The repositories to review, owner/name, comma-separated.
GITHUB_PAT	The service token: a fine-grained PAT covering every repo in REPOS with Pull requests: Read and write, Contents: Read, Metadata: Read. It reads and polls, never posts; posting and approving use each reviewer’s own token.

Open http://localhost:8899, then run the doctor:

docker compose exec app doctor

One PASS / WARN / FAIL line per check. Then:

1. Sign in with GitHub — a short code at github.com/login/device, nothing to register.
2. Connect Claude on the welcome checklist; reviews bill to your plan.
3. Paste a PR URL: your first review.

DRY_RUN=1 ships on: every button works, but nothing is written to GitHub until you set DRY_RUN=0 and restart. Compare a few dry runs with your own reviews first.

docker compose --profile team up -d   # adds the poller and Slack/Discord cards

Read the security model first

ReviewStage checks out branches and runs an agent over code an external contributor may have written. Before you point it at a pull request that is not your own, read Security.

Next: Team workflow for how it fits your review process, Team mode for the poller and many repositories, Configuration for every knob, proxies, ports and your own OAuth App.

From source on a Linux server

You get the same server as the Docker install, as a systemd unit behind your own web server. Use this when you cannot run Docker.

The pieces are a Python 3 server, a few bash scripts, the Claude Code CLI and the GitHub CLI. There is no build step for the backend; the dashboard UI is a prebuilt bundle.

bin/bootstrap.sh is idempotent and does six things:

1. Installs gh and claude if missing.
2. Copies the scripts to ~/.reviewstage/bin/ and creates ~/.reviewstage/.env (chmod 600), adding only missing keys, so re-running never overwrites your values.
3. Makes one blobless base clone per repository in REPOS.
4. Installs the built-in review skill and seeds the editable team default.
5. Writes and starts reviewstage.service, bound to 127.0.0.1:8899.
6. Installs the cron entry for the poller (every 3 minutes).

sudo -iu <service-user>          # the user the unit runs as
claude                           # sign Claude Code in as that user, interactively
~/reviewstage/bin/bootstrap.sh   # prompts for REPOS and your GitHub login
# paste GITHUB_PAT (and SLACK_WEBHOOK if wanted) into ~/.reviewstage/.env
~/reviewstage/bin/bootstrap.sh   # re-run to finish; safe at any point
curl -s localhost:8899/health    # -> ok

Put a TLS-terminating reverse proxy in front (Caddy is two lines) and read Security before turning DRY_RUN off. The server reads .env once at startup: restart it after any edit.

The most common failure is signing Claude Code in as a different user than the one the service runs as. The credentials land in the wrong home directory and every review finishes instantly with an empty result.