Put your panel to work.
Install the relay, choose your reviewers, and get a scored review on your next pull request.
Quick start
You need Git, the GitHub CLI, a local clone of each watched repo, and at least one supported coding agent. Sign in to your agents or configure their API keys before starting.
1. Connect GitHub
Your GitHub account needs permission to manage repository webhooks and, when publishing is enabled, write PR comments.
gh auth login
gh extension install cli/gh-webhook
gh auth status2. Install review-relay
$ curl -fsSL https://github.com/Tyru5/review-relay/releases/latest/download/install.sh | bashStandalone binaries for macOS and glibc Linux on x64/arm64, and Windows x64. No Bun or Node installation required. Alpine/musl is not supported.
3. Choose your repos and start
review-relay setup
review-relay start -d
review-relay tuisetup finds GitHub clones under your home directory and agent CLIs on your PATH. Choose the repos, reviewers, models, and effort. It saves ~/.review-relay/config.json. tui shows the jobs live as the daemon runs them; status prints a one-shot summary.
review-relay run --repo acme/widget --pr 42No pull request yet? Run review-relay review inside the clone to score the checked-out branch without GitHub or the daemon. See Review before a PR.
Use start without -d for foreground logs. The machine and daemon must stay running to receive events.
Install locations, updates, and pinned versions
Unix installs to ~/.local/bin/review-relay. Add ~/.local/bin to your PATH if needed. Windows installs to %LOCALAPPDATA%\review-relay\bin and adds it to your user PATH by default.
Both installers also add rr as a shortcut for review-relay. An existing rr from another tool is left alone.
The installers verify the binary’s SHA-256 checksum and preserve an existing config. Run the installer again to update, then restart the daemon. To pin a release, pass --version x.y.z to the Unix installer, or -Version x.y.z to the PowerShell script.
Unix also accepts --bin-dir and --no-alias. PowerShell accepts -BinDir, -NoModifyPath, and -NoAlias. See environment variables for equivalent settings.
Configuration
Configuration is JSON. The CLI uses --config <path> first, then REVIEW_RELAY_CONFIG, then ~/.review-relay/config.json. Restart the daemon after editing it.
{
"reviewers": [
"codex",
"claude"
],
"repos": [
{
"fullName": "acme/widget",
"localPath": "~/code/widget",
"trigger": "github",
"postToPr": false
}
]
}This example watches a fictional repo through GitHub events and keeps reports local. Replace fullName and localPath, then set postToPr to true when you want comments.
Top-level options
| Option | Default | What it does |
|---|---|---|
repos | Required | Non-empty list of GitHub repositories and their local clones. |
port | 9988 | Local webhook server port, 1 to 65535; 0 picks a free one. Listens on 127.0.0.1 only. |
graceMs | 120000 | In auto mode, wait this many milliseconds for Greptile or CodeRabbit before the GitHub fallback runs. |
timeoutMs | 1800000 | Per-reviewer timeout in milliseconds. The default is 30 minutes. |
maxConcurrent | 2 | Reviews that run at once, each with its whole panel. Later ones queue, oldest first. |
reviewers | ["codex","claude"] | Fallback panel when no route matches. At least one reviewer ID is required. |
models | Built-in entries | Model, effort, provider, and display label per reviewer. Custom entries also name a harness. |
routes | [] | Ordered rules that select reviewers or skip an automatic review. |
pricing | {} | USD per million tokens by model, as { input, output, cachedInput?, cacheWrite? }. Adds to or overrides the built-in prices used to estimate Codex costs. |
dataDir | ~/.review-relay | Reports, state, logs, and temporary worktrees. Does not change the config file location. |
theme | "dark" | TUI colors: dark, light, or terminal to sync with your terminal. Press t to switch and save. |
Repository options
Each object in repos accepts these settings. Use an absolute path, or ~/, so the clone resolves consistently.
| Option | Default | What it does |
|---|---|---|
fullName | Required | GitHub owner/name, for example acme/widget. |
localPath | Required | Existing local clone with an origin remote for this repository. ~/ expands to your home. Relative paths resolve from the process working directory. |
trigger | auto | auto, greptile, coderabbit, or github. Mentions work in every mode. |
postToPr | true | Publish the report as a PR comment. Set false for local reports only; reviewers still run. |
status | false | true or { minScore: 1-5 } sets a review-relay commit status on each reviewed commit: success at minScore (default 4) or above, so branch protection can require it. |
inlineComments | false | Also post each new finding on its changed line as one PR review, with a suggestion block when the fix is a small edit. Needs postToPr. |
github.onPush | false | Also handle pull_request.synchronize when new commits are pushed. Applies to github and auto modes. |
github.mention | @review-relay | Case-insensitive text that requests a review in a new PR comment. Use a non-empty mention. |
authors | [] | GitHub logins whose PRs get reviewed, case-insensitive; write apps as dependabot[bot]. Empty reviews every author. Mentions and run review any PR. |
review-relay info --config ./relay.json
review-relay start -d --config ./relay.jsonUse the same --config for status, stop, and other commands targeting that daemon. info --json and config show resolved values, including defaults; config -h lists every key as a jq path. config edit opens the file in $EDITOR and checks it after you save. config check reports every problem, including repos with no clone and reviewer CLIs missing from PATH, and exits 0 when it passes, 1 when it fails, 2 when the file is not JSON, and 3 when there is none; --strict exits 4 on warnings, and --json prints the report for scripts.
Environment variables and installer overrides
| Option | Default | What it does |
|---|---|---|
REVIEW_RELAY_CONFIG | ~/.review-relay/config.json | Config path for the CLI and installers. --config takes precedence in the CLI. |
REVIEW_RELAY_DEBUG | Not set | Any non-empty value logs why webhook events were ignored. Set before starting the daemon. |
NO_COLOR | Not set | A non-empty value disables CLI color, even if FORCE_COLOR is set. |
FORCE_COLOR | Not set | A non-empty value other than 0 enables CLI color. |
REVIEW_RELAY_INSTALL_VERSION | latest | Installer release version. Unix --version and PowerShell -Version take precedence. |
REVIEW_RELAY_INSTALL_BIN_DIR | Platform default | Installer destination. Unix --bin-dir and PowerShell -BinDir take precedence. |
REVIEW_RELAY_INSTALL_REPO | Tyru5/review-relay | GitHub repo to download releases from. Only use a repo you trust. |
REVIEW_RELAY_INSTALL_NO_MODIFY_PATH | Not set | Windows only. Any non-empty value prevents PATH changes; equivalent to -NoModifyPath. |
REVIEW_RELAY_INSTALL_NO_ALIAS | Not set | Any non-empty value skips the rr shortcut; equivalent to --no-alias or -NoAlias. |
Agent authentication belongs to each agent CLI. review-relay does not store API keys in its config.
Reviewers & models
reviewers names the default panel. Every ID selects a built-in CLI or a custom entry in models. Selected reviewers run in parallel; they do not need to use different CLIs.
| Reviewer ID | Product | Relay defaults |
|---|---|---|
claude | Claude Code | claude-opus-5-5, effort max |
codex | Codex CLI | gpt-6-astra, effort high |
auggie | Augment Auggie | CLI default model; effort supported |
copilot | GitHub Copilot CLI | CLI default model; effort supported |
droid | Factory Droid | CLI default model; effort supported |
gemini | Gemini CLI | CLI default model; no per-run effort option |
grok | Grok Build | CLI default model; effort supported |
hermes | Hermes Agent | CLI default model; effort supported |
kilo | Kilo Code CLI | CLI default model; effort supported |
opencode | opencode | CLI default model; effort supported |
pi | pi | CLI default model; effort supported |
qwen | Qwen Code | CLI default model; no per-run effort option |
vibe | Mistral Vibe | CLI default model; no per-run effort option |
The executable normally matches the ID. Kilo also accepts kilocode. Install and authenticate each selected CLI separately; review-relay does not install agents.
Model entry options
| Option | Default | What it does |
|---|---|---|
harness | Required for custom IDs | One of the supported CLI IDs below. A built-in ID always uses its own CLI. |
label | CLI label or custom ID | Name shown in the PR comment. Active reviewer labels must be unique, ignoring case. |
model | Harness default | Model identifier accepted by the CLI. Omit to use the relay default below, or the CLI default when none is set. |
effort | Harness default | Reasoning setting for CLIs that support it. Model and CLI versions determine which values work. |
provider | Not set | Hermes only. Provider identifier, separate from the model name. |
For example, models.codex changes the built-in Codex reviewer. To run two Codex models, create two custom IDs with harness: "codex" and put both IDs in reviewers.
Custom IDs use up to 32 lowercase letters, digits, and dashes, starting with a letter or digit. Omitted settings inherit the harness defaults, not another entry’s overrides. Add or remove custom entries in JSON; setup can edit existing entries.
Unknown custom-entry fields are errors. Invalid legacy built-in settings may warn and be ignored. Unsupported model or effort values can still be rejected by the agent CLI at runtime.
Routing rules
Routes choose a panel from the PR’s diff and trigger. The first matching, applicable route wins. If none matches, the global reviewers and timeoutMs apply.
{
"reviewers": [
"codex",
"claude"
],
"models": {
"codex-deep": {
"harness": "codex",
"label": "Codex deep",
"model": "gpt-6-astra",
"effort": "high"
}
},
"routes": [
{
"name": "docs-only",
"when": {
"onlyPaths": [
"docs/**",
"**/*.md"
]
},
"skip": true
},
{
"name": "sensitive",
"when": {
"wideImpact": true
},
"reviewers": [
"codex-deep",
"claude"
],
"timeoutMs": 2400000
},
{
"name": "small",
"when": {
"maxLines": 100,
"maxFiles": 5
},
"reviewers": [
"codex"
]
}
],
"repos": [
{
"fullName": "acme/widget",
"localPath": "~/code/widget",
"trigger": "auto",
"postToPr": false
}
]
}This example skips documentation-only automatic reviews, sends sensitive changes to a larger panel, and sends small changes to Codex. Everything else uses the default panel.
Route options
| Option | Default | What it does |
|---|---|---|
name | Required | Unique ID, up to 32 lowercase letters, digits, and dashes; starts with a letter or digit. |
when | Required | Non-empty object of conditions below. All conditions must match. |
reviewers | Either reviewers or skip | Non-empty list of known reviewer IDs, without duplicates. Replaces the fallback panel. |
skip | Omit for review routes | Set true instead of reviewers to skip. Skip routes cannot set timeoutMs. |
timeoutMs | Global timeoutMs | Positive integer in milliseconds. Overrides the timeout for each reviewer on this route. |
Match conditions
All conditions in when must hold. Lists match any listed value or glob. Path globs use repository-relative paths and are case-sensitive. Use ** to span directories.
| Condition | Value | Matches when |
|---|---|---|
repos | Glob list | Match owner/name, ignoring case. Each pattern must match at least one configured repo. |
baseBranches | Glob list | Match the target branch, not the PR head branch. Case-sensitive. |
sources | Value list | greptile, coderabbit, github, mention, manual, or local. |
paths | Glob list | At least one changed path matches. Includes the old path of a renamed file. |
onlyPaths | Glob list | Every changed path must match at least one pattern, including both sides of renames. Empty diffs do not match. |
minLines | Integer ≥ 0 | Minimum additions + deletions, inclusive, excluding recognized lockfiles. |
maxLines | Integer ≥ 0 | Maximum additions + deletions, inclusive, excluding recognized lockfiles. |
minFiles | Integer ≥ 0 | Minimum number of changed non-lockfiles, inclusive. |
maxFiles | Integer ≥ 0 | Maximum number of changed non-lockfiles, inclusive. |
wideImpact | Boolean | Match changes to recognized dependency manifests, CI, migrations, schemas, SQL, environment files, and other sensitive paths. False matches their absence. |
Size conditions exclude recognized lockfiles; path conditions still see them. Binary files count as files with zero added or deleted lines. Renames consider both old and new paths.
Request a named panel
@review-relay sensitiveA trusted commenter can name a non-skip route after the mention. That route runs even if its conditions do not match. Unknown names and skip-route names fall back to normal routing.
Route names must be unique. Unknown fields, duplicate reviewers, empty conditions, and a minimum above its maximum stop config loading.
Triggers & review flow
| Mode | Starts on | Behavior |
|---|---|---|
auto | Greptile, CodeRabbit, or GitHub | Default. A Greptile or CodeRabbit start runs immediately. A GitHub PR event waits graceMs, then runs if neither bot has started for that commit. |
github | GitHub PR events | Runs immediately on opened, reopened, and ready_for_review. Add github.onPush: true for synchronize events. |
greptile | Greptile check start | Only the Greptile start triggers automatic reviews. No GitHub fallback. |
coderabbit | CodeRabbit review start | Only the CodeRabbit start triggers automatic reviews. No GitHub fallback. |
Mentions work in every mode. Only new PR comments by an OWNER, MEMBER, or COLLABORATOR qualify. Bot comments and ordinary issues do not.
- Receive an event. Each repo has a temporary webhook forwarded through
gh webhook forwardto the local signed endpoint. No public relay URL is needed. - Resolve and deduplicate. The scheduler keys automatic reviews by repository and head commit. Completed, skipped, cancelled, queued, and in-progress jobs suppress duplicates. Failed jobs can retry on another trigger. At most
maxConcurrentreviews run at once; the rest wait asqueued. - Check the commit is current. When a job’s turn comes, it runs only if its commit is still the PR’s head on GitHub, and it stops any review still running on an older commit of that PR. Either way the stale job is recorded as
superseded. - Choose the route. Fetch the PR and base branch, inspect the diff, and select reviewers. A skip stops before a worktree is created.
- Run the panel. Create a detached worktree, remove executable project-level agent config, and run the selected CLIs concurrently against the same rubric.
- Save and publish. Remove the temporary worktree, save reports, and create or update a PR comment if enabled, then the inline review when it is on. The comment is posted only if the commit is still the PR’s head, one post per PR at a time, so a slow review of an older commit never replaces a newer one’s comment.
- Report the result. Set the commit status and send notifications, when configured. The status went
pendingwhen the review started.
A cancel stops a job at any of these steps: a queued job never starts, and a running one kills its reviewers, removes the worktree, posts nothing, and is recorded as cancelled.
GitHub PR events ignore drafts and closed PRs. Explicit mentions and manual runs require an open PR but can review a draft. They bypass completed-job deduplication, but not an already-running job in the same scheduler.
Greptile matching requires app greptile-apps, check name Greptile Review, and a created check that is queued or in progress. Completed checks only log a result. Fork checks without an associated PR are ignored; use auto for the GitHub fallback.
CodeRabbit matching requires a CodeRabbit commit status set by coderabbitai[bot] to pending with Review in progress. Review queued and Review skipped: ... do not start a review. The status names only a commit, so the open, non-draft PR whose head is that commit is looked up, forks included. A check run created by the coderabbitai app, other than CodeRabbit Security, also counts, for installs that report progress through check runs.
Review before a PR
review-relay review scores the branch you have checked out, so you can rate a change before opening a pull request. It runs in your own clone, needs no PR, no GitHub access, and no running daemon, and posts nothing.
- Foreground, the default, waits for the reviewers and prints the score, findings, and dimension notes. Use it in scripts and hooks.
- Background, with
-d, returns at once. A background process reviews the commitHEADwas at, so you can keep working while it runs. Follow it inreview-relay tuiorreview-relay logs -f.
review-relay review
review-relay review -d
review-relay review --base origin/main --min-score 4
review-relay review --reviewers claude,codex --json- Same range as the PR. It reviews the commits on
--head(defaultHEAD) that--baselacks. The base defaults to the remote’s default branch as the clone recorded it (origin/HEAD), elseorigin/main. - Same panel and score. The reviewers, rubric, lockdown, caps, and lowest-score headline match a PR review. Linked worktrees work too.
- Committed work only. Uncommitted changes are left out with a warning. Nothing is fetched, so run
git fetchfirst for an up-to-date base. Both refs are pinned to commits when the review starts. - Any clone. The repo’s config entry applies when one names the clone. Any other clone still works, named from its origin remote or its folder.
| Option | Default | What it does |
|---|---|---|
-d, --detach | Foreground | Review in the background and return at once. Follow it in tui or logs -f. |
--base <ref> | origin/HEAD, else origin/main | Ref to diff against. Any ref works: a remote branch, a local branch, or a SHA. |
--head <ref> | HEAD | Ref to review. Uncommitted changes are only checked, and left out, when this is HEAD. |
--route <name> | Normal routing | Use this non-skip route instead of the one the branch matches. |
--reviewers <ids> | Normal routing | Comma-separated reviewer IDs to run instead of routing. Not with --route. |
--min-score <n> | None | Exit 1 when the confidence is under n, from 1 to 5. Foreground only. |
--json | Off | Print the score, each reviewer’s result, and the merged findings as JSON. Foreground only. |
Routes pick the reviewers as they would for a PR, with source local and the base’s branch name (main for origin/main). A skip route never applies, and "sources": ["local"] sends local reviews to a panel of their own.
Both ways record the job, so status and tui list it with its branch in the PR column and local as its source, and save the report under <dataDir>/reports/<owner__repo>/local/<sha8>/. In tui, r reviews the branch’s current head again in the background, in the checkout it ran in, and c cancels it while it runs. Each local review is its own process, so maxConcurrent does not limit them.
Merge gate & alerts
Three opt-in settings carry the score past the comment: a commit status a branch protection rule can require, comments on the lines findings name, and notifications. Each is off until you set it.
{
"repos": [
{
"fullName": "acme/widget",
"localPath": "~/code/widget",
"status": {
"minScore": 4
},
"inlineComments": true
}
],
"notify": {
"on": [
"low",
"failed"
],
"desktop": true,
"ntfy": "https://ntfy.sh/your-unguessable-topic"
}
}Commit status
With status on, each reviewed commit gets a review-relay status: pending while the panel works, then success when the confidence is at least minScore (default 4, “minor issues only”) and failure under it. A skip route passes; a failed or cancelled review is an error; a superseded commit is left alone, since the PR’s new head gets its own. The status links to the PR comment.
It is a commit status rather than a check run because GitHub only lets GitHub Apps create check runs, and gh signs in as you. A status that fails to post is logged and never fails the review.
Inline comments
With inlineComments on (it needs postToPr), each review also posts its new findings as one COMMENT review, each on the line it names. Findings still open from an earlier commit were commented on then. GitHub rejects a whole review when one comment names a line outside the diff, so a finding on an untouched line stays in the summary comment alone.
Reviewers can give each finding the exact replacement for its lines. When every line of the range was added by the PR, the comment carries a suggestion block GitHub applies in one click. A mention or run that reviews the same commit again skips spots already commented on. A failed inline post is logged; the summary comment stands.
Notifications
notify needs at least one channel. Notifications come from the daemon, run, and background local reviews; a foreground review prints its result instead. Skipped, superseded, and cancelled reviews send nothing, and a channel that fails is logged without failing the review.
| Option | Default | What it does |
|---|---|---|
on | ["low","failed"] | done: every finished review. low: confidence under minScore. failed: the review failed, or every reviewer did. |
minScore | 4 | The threshold for low, from 1 to 5. |
desktop | false | macOS osascript, Linux notify-send, or a Windows toast; on WSL without notify-send, the Windows toast. |
ntfy | None | An ntfy topic URL. Gets the text, with Title, Tags, and Click headers. |
slack | None | A Slack incoming webhook URL. Gets { text }. |
webhook | None | Any URL. Gets JSON: event, repo, pr, branch, local, headSha, score, findings by severity, reviewers, url, error, title, text. |
Pre-push hook
review-relay hook install
review-relay hook install --min-score 3
review-relay hook uninstallhook install writes a pre-push hook in the checkout’s hooks folder, following core.hooksPath. Each pushed branch with commits no remote has yet gets a local review, and the push stops when the confidence is under --min-score (default 4) or the review fails. Tags, deletions, and branches already on a remote pass. git push --no-verify skips it.
The hook calls review-relay by absolute path, since GUI git clients often run hooks without your shell PATH. A pre-push hook review-relay did not write is left alone; install prints the line to add to it. The push waits for the review, so a cheap route with "sources": ["local"] keeps it short.
Agents & MCP
review-relay mcp serves review-relay to agents over the Model Context Protocol on stdin and stdout, so an agent can score the branch it is working on before it opens a PR, or review a PR, and act on the findings. Register it with your agent’s client as a stdio server that runs review-relay mcp.
claude mcp add review-relay -- review-relay mcp # Claude Code
codex mcp add review-relay -- review-relay mcp # CodexOther clients take the same command in their MCP config. Add --config <path> to the arguments for a config other than the default.
{
"mcpServers": {
"review-relay": {
"command": "review-relay",
"args": [
"mcp"
]
}
}
}Tools
| Tool | Arguments | What it does |
|---|---|---|
review_branch | path, base, head, route | reviewers, waitSeconds | Start a local review of a checkout’s branch, like review -d. path defaults to the directory the client started the server in. Posts nothing. |
review_pr | repo, pr, route, waitSeconds | Start a review of an open PR in a configured repo, like run. Posts the comment when the repo has postToPr on, inline comments with inlineComments, and the commit status with status. |
get_review | key | repo + pr | none, waitSeconds | A job’s status and, once it finishes, its score, each reviewer’s score, summary, and dimension notes, and the merged findings with file, line, detail, and suggestion. With no key, the PR’s latest review, or the newest job. |
list_reviews | repo, pr, status, limit | Recent jobs, newest first, with status, score, finding counts, and cost. status is queued, running, done, failed, skipped, superseded, or cancelled. |
- Reviews run in the background. A review takes minutes, longer than many clients wait for one tool call, so the start tools return the job’s
keyat once and a separate process runs the review, asreview -ddoes. Until that process records the job, its status isstarting. - Wait when you want to.
waitSeconds, up to 600 on the start tools andget_review, holds the call until the review finishes, sending progress notifications to clients that ask for them. A process that exits before recording the job fails the call with the lines it logged. - Same jobs as everywhere else. They land in
state.json, sostatus,cost, andtuishow them, and their output goes todaemon.log. Starting a review of a commit already under review returns that job instead of starting another. - Config read on every call. Edits apply without restarting the client. A missing or broken config comes back as a tool error.
CLI commands
Run review-relay help <command> or review-relay <command> --help for command help. Global options are --config <path>, -h / --help, and -v / --version.
| Command | Arguments / options | Purpose |
|---|---|---|
setup | No required flags | Interactive repo and reviewer selection. Writes the config and preserves settings it does not ask about. |
start | -d, --detach | Watch repos. Foreground by default; -d runs in the background and writes daemon.log. |
stop | No flags | Stop the background daemon. Attempts graceful shutdown, then forces exit after 20 seconds. |
restart | No flags | Stop, then start in the background. Use after editing config. |
instances | --json | Remote sessions, GitHub accounts, machine labels and heartbeats. Opt in with presence: { repo: "owner/private-repo", issue: 1, label: "laptop" } on every machine, using the same existing private issue. Labels and process states are self-reported. Heartbeats expire after three minutes; lookup failures are unknown (exit 2), never proof of absence. Warns without stopping remote daemons. |
status | --limit <n>, --page <n> | Daemon, endpoint, forwarders, and recent jobs. 20 jobs per page; --page reaches older ones. Exits 3 when the daemon is not running. |
cost | [--repo <owner/name>] [--pr <n>] [--limit <n>] [--page <n>] [--json] | What each finished review cost, per reviewer, with totals. Claude Code reports its own cost; Codex costs are estimated from tokens (marked ~). |
scorecard | [--repo <owner/name>] [--json] | How each reviewer’s findings fared on the PR’s next commit: addressed, attempted, ignored, or dropped by the reviewer itself. Judged by diffing consecutive reviewed commits in the local clone. |
tui | No flags | Live terminal view of the jobs, local reviews included. Enter opens scores, findings, and the posted comment; r re-reviews a PR or branch, c cancels a running review, o opens the PR, / filters. |
logs | [N], -f, --follow | Read the last N log lines, default 50. Use -f to follow new output. |
run | --repo <owner/name> --pr <n> [--route <name>] | Review an open PR now, including a previously reviewed commit. Can publish a comment. |
review | [-d] [--base <ref>] [--head <ref>] [--route <name> | --reviewers <ids>] [--min-score <n>] [--json] | Score the checked-out branch before opening a PR. Prints the report and exits 1 under --min-score, or with -d runs in the background and shows in tui. Posts nothing. |
hook | install [--min-score <n>] [--base <ref>] [--route <name> | --reviewers <ids>] | uninstall | Write a git pre-push hook that runs review on each pushed branch with new commits and blocks the push under --min-score (default 4). git push --no-verify skips it; a hook review-relay did not write is left alone. |
cancel | [--repo <owner/name> --pr <n>] [--head <branch>] | Cancel the PR’s queued or running reviews, or with neither flag the local reviews running in this checkout. The reviewers stop, nothing is posted, and the job is recorded as cancelled. |
route | --repo <owner/name> --pr <n> [--source <source>] | Explain matching rules without running reviewers or posting. Fetches the PR and base refs. Default source: github. |
mcp | No flags | MCP server on stdio for agents: review_branch, review_pr, get_review, and list_reviews. Reviews run in the background and show in status and tui. |
replay | <events.jsonl> --dry-run --grace <ms> | Process recorded deliveries. --dry-run logs would-run jobs; --grace overrides the auto-mode wait for this replay. |
info | --json | Resolved configuration and diagnostics. --json prints machine-readable output. |
config | [edit|check] --json --strict | Print the resolved configuration as JSON, colored on a terminal; -h lists every key as a jq path. edit opens the file in $VISUAL or $EDITOR and checks it after you save. check reports every problem, including missing clones and reviewer CLIs, and exits 0 pass, 1 fail, 2 corrupted, 3 missing, or with --strict 4 on warnings; --json prints the report. |
help | [command] | List commands, or show a command’s options and examples. |
Watch jobs live
review-relay tuitui takes over the terminal: the job table in a panel taking about four fifths of the screen, the highlighted job’s detail in a panel below it, and the daemon’s state and the total spent in the status line, refreshing as the daemon writes state.json. Enter expands a job: the published score, each reviewer’s score, model, cost, and time, the merged findings with their file and line, and the review comment from comment.md, which is only posted to the PR when postToPr is on and a reviewer succeeded. A job with no comment yet shows its log lines instead.
The table has a COST column and a PR STATE column that shows GitHub’s open, closed, or merged state apart from the review result. The TUI checks nearby rows through your signed-in gh in the background, at most once a minute; unchecked PRs show unknown and local reviews -.
| Key | Where | What it does |
|---|---|---|
enter | Job list | Open the job: scores, findings, and the posted comment, or its log lines while it runs. |
[ ] | Job | Select the previous or next Details or Dimension notes section; enter or space expands or collapses it. |
← → | Any | Pan a table or line wider than the screen. They only pan, and stop at the edges. |
l | Any | Follow the job’s lines from the daemon log as they arrive. |
L | Any | The whole daemon log. |
i | Any | Remote instances and overlap warnings. Requires presence configuration; esc returns to jobs. |
/ | Job list | Filter by repo, PR, commit, status, source, route, or error text. |
s | Job list | Cycle the status filter: queued, running, done, failed, skipped, superseded, cancelled, all. |
r | Any | Review the PR, or a local review’s branch, again in the background. Asks first. |
c | Any | Cancel a queued or running review. Asks first; its reviewers stop and nothing is posted. |
o | Any | Open the PR in the browser. |
y | Any | Copy the PR’s URL. |
t | Any | Cycle the theme: dark, light, terminal. Saved to the config without restarting the daemon. |
q | Any | Quit. esc goes back, clears the filters, then quits. |
? lists every key. The TUI reads state.json, the report directories, and daemon.log directly, so it works whether or not the daemon is running. A queued or running job whose process has exited shows as failed in both tui and status, so it can retry.
Themes, small terminals, and wide rows
t cycles Dark, Light, and Terminal. Terminal uses your terminal’s own foreground, background, and ANSI palette and follows its theme changes; Dark and Light use truecolor where the terminal supports it. The choice is saved as theme in the active config without restarting the daemon, and NO_COLOR still disables color in every mode.
On a narrow terminal the table, a job’s detail, and the log pan sideways with ← and →, and the panel’s top edge counts the columns hidden on each side. A long message wraps onto up to three rows instead of being cut. The status line and footer drop their least important parts first, and the detail panel is dropped when the terminal is too short for both. The layout needs at least 40 columns by 10 rows.
Cancel a review
review-relay cancel --repo acme/widget --pr 42
review-relay cancel
review-relay cancel --head featureWith --repo and --pr, cancel stops the PR’s queued or running reviews. With neither, it stops the local reviews running in the checkout you run it from, and --head narrows that to one branch. In tui, c does the same for the highlighted job, after asking.
The request is written to state.json. Whichever process runs the review (the daemon, run, or a local review) notices within a second, stops its reviewers, removes the worktree, posts nothing, and records the job as cancelled; until then the job shows as cancelling. cancel waits up to 20 seconds for that, and exits 1 when there was nothing to cancel or a review did not stop in time. Triggers leave a cancelled commit alone, while run, a mention, or r in the TUI reviews it again.
Preview or force a route
review-relay route --repo acme/widget --pr 42 --source githubrun --route sensitive forces that non-skip route. Unlike mentions, an unknown or skip route is rejected. route --source accepts github, greptile, coderabbit, mention, manual, or local. Route inspection also works on closed PRs.
Replay recorded deliveries
Use a JSONL file with one {"event":"pull_request","payload":{...}} object per line. body is accepted as an alternative to payload. The payload must contain the original GitHub fields.
review-relay replay events.jsonl --dry-run --grace 0Dry-run uses fresh in-memory state and logs which jobs would be dispatched. It does not fetch diffs or evaluate routes. Without --dry-run, replay can run agents, write state, and publish comments.
Scores & reports
Each successful reviewer scores correctness, security, code quality, standards, blast radius, and testing from 1 to 5, plus an overall merge confidence.
- A critical finding caps that reviewer at 2/5.
- A major finding caps that reviewer at 3/5.
- Overall confidence cannot exceed the weakest dimension by more than one point.
- The published score is the lowest capped score among successful reviewers, never an average.
Findings from different reviewers at the same file and within three lines are merged, retaining the highest severity. The comment links findings to the reviewed commit and includes dimension notes.
One comment, local reports
Publishing edits the signed-in GitHub user’s latest comment carrying the relay marker, or creates one if none exists. Switching GitHub accounts can create a separate comment. Scores are advisory unless you turn on the commit status and require it in branch protection.
<dataDir>/reports/<owner__repo>/pr-<number>/<sha8>/
comment.md
<reviewer-id>.json
findings.json
meta.json
<dataDir>/reports/<owner__repo>/local/<sha8>/ # review, before a PRmeta.json records the job, route, selected models, timeouts, durations, scores, and each reviewer's tokens and cost (Claude Code's own figure; Codex estimated from tokens at list price), which cost totals. Reviewer JSON contains the verdict, or an error and raw output on failure. Re-running the same PR commit writes to the same directory. tui renders these reports in the terminal: open a job to read its scores, findings, and comment.md without leaving the shell.
One failed reviewer does not cancel the others. A partial result can publish with the failure noted. If all reviewers fail, local reports are saved but no comment is posted, and the job fails. A publishing failure also leaves the local report available.
Agreement, history, and a scorecard
Each finding names the dimension it counts against. Findings several reviewers reported on the same spot merge into one with the worst severity, badged consensus when every reviewer had it and majority when more than half did, and minority when more than one but half or fewer did; a finding one reviewer alone caught carries no badge, and is often the one worth reading first. Within a severity, the agreed-on findings come first.
A PR’s later reviews are tracked against its last reviewed commit: the comment says how many findings are new, still open since the commit they first appeared on, and fixed (reported before, repeated by no reviewer now), with the fixed ones in a collapsed list. Two findings match when they name the same file and their titles are alike, or both name lines within 3 of each other and their dimensions don’t disagree. The tracked findings are findings.json, and get_review returns them.
review-relay scorecard
review-relay scorecard --repo acme/widget --jsonscorecard pairs each PR review with the next review of the same PR, diffs the two commits in the local clone, and sorts each finding: addressed (its lines changed, nobody reported it again), attempted (lines changed, reported again), ignored (lines unchanged, reported again), or dropped (lines unchanged, no reviewer repeated it: likely noise); a finding that names no file is unknown, and one whose reviewers all failed next time waits for a later pair. Per reviewer it adds how many findings were its alone and acted on, how often others agreed, how many critical or major findings went nowhere, how its scores lean against the panel, and the cost per addressed finding. Reviews nothing followed are not judged.
What a review cost
review-relay cost
review-relay cost --repo acme/widget --pr 42
review-relay cost --json | jq .costUsdcost lists the finished reviews newest first with each reviewer’s cost and tokens and the review’s total, then the totals across them, overall and per reviewer. --repo and --pr narrow it, --limit and --page page it like status, and --json prints every matching review. status and tui show the same COST column.
- Claude Code reports its own cost, at list price even on a subscription, and it is used as is.
- Codex reports only tokens, so its cost is those tokens at the model’s list price, marked
~. Built-in prices covergpt-6-astra,gpt-6-sol,gpt-6.1-sol, andgpt-6-luna;pricingin the config adds a model or changes a price, and a run whose model had no price when it ran is priced when it is read. - Other CLIs do not report usage yet, so their columns show
-. A total that leaves out a run with no cost, such as one that timed out, is marked+. - A re-review of the same commit replaces its report, cost included, so
costcounts the latest run of each commit.
Security & privacy
Reviews run on your machine, but your code goes to the providers used by your selected agents and models. postToPr: false disables GitHub comments, not provider requests.
The webhook server binds to 127.0.0.1. POST /hook requires an HMAC-SHA256 signature using a secret generated at daemon startup. GET /health returns a local health response.
Reviewers use each CLI’s read-only controls, restricted tools, sandbox, or no-shell mode. The runner removes recognized project configs that could load hooks, plugins, or MCP servers from the review worktree before starting agents. Your original clone is not stripped.
These controls depend on the agent CLI and its version. They are not a separate VM boundary. Keep CLIs updated, review their authentication and provider settings, and treat PR content and model output as untrusted.
Inline suggestions are model output, and PR content can steer the model, so read a suggestion before applying it. Notifications send the repo, PR or branch, score, and finding counts to the URLs you set; a public ntfy topic is readable by anyone who knows its name.
Reports and daemon logs can contain source code and findings. Protect dataDir accordingly. GitHub removes each forwarder’s temporary repository webhook as soon as the forwarder’s connection closes. On macOS and Linux, stopping the daemon leaves none behind; on Windows, end any leftover gh webhook forward processes by hand.
Troubleshooting
review-relay status
review-relay info
review-relay logs 100
gh auth statustui shows a job’s log lines while it runs, and l opens them for any job, including a failed one whose saved comment fills the detail view. r re-runs it once the cause is fixed.
No review appeared
Check that the daemon and repo forwarder are running, your machine is awake, and fullName matches. In auto mode, allow the two-minute default grace period. Push events require github.onPush: true. Check for a draft, already-reviewed commit, or skip route.
For mention triggers, use a new PR comment from a trusted collaborator. To see ignored-event reasons, set REVIEW_RELAY_DEBUG=1 in the daemon’s environment and restart it.
A reviewer failed or timed out
Confirm its executable is on the daemon’s PATH and that the CLI can authenticate outside review-relay. Check model and effort support. Read that reviewer’s JSON in the report directory for the error and raw output. Increase timeoutMs if needed, then restart.
A failed job can retry on a later trigger. A partial review is completed, so use a mention or run to request it again.
Config edits had no effect
Run info with the same --config as the daemon. It flags unapplied edits, missing binaries, and missing clones. The daemon does not hot-reload its config; use restart.
The report exists but there is no PR comment
Check postToPr, GitHub authentication, and permission to comment. If every reviewer failed, the relay saves the report without publishing. Read comment.md and the log before retrying.
Port conflict, stale daemon, or leftover webhooks
status distinguishes a live relay from a stale daemon record or a different listener. Do not stop an unrelated service. Choose another port or stop the correct relay before starting again.
A forwarder that outlives its daemon, after a crash or a forced stop, keeps its temporary webhook until its connection closes: end the gh webhook forward process by hand; GitHub drops its webhook within a second, and a forwarder standing by picks it up on its next try. A forwarder started while another instance holds the repository logs that it is standing by and tries again every 30 seconds; status shows it as standby.
The review-relay status is missing, stuck, or no notification came
info shows status ≥N and inline on on each repo and the notify channels. A daemon started before the edit needs restart. A status or notification that failed to send is logged with the reason: search logs for commit status not set or notification failed.
A status left pending means the process stopped mid-review; a mention or run reviews the commit again and replaces it. Drafts and skipped authors never get one.
An agent’s MCP call failed or never finished
A tool error names a missing or broken config; fix the file and call again, since the server reads it on every call. A start tool that fails quotes the lines the review process logged. A job left at starting or running shows up in tui and logs like any other, so read its log lines there. Long reviews outlast many clients’ tool timeouts: start without waiting, then poll get_review with a shorter waitSeconds.
Git cannot fetch the PR
Check that localPath is an existing clone with an origin remote pointing at the configured GitHub repository. Confirm Git authentication works for that remote. The relay fetches the base branch and refs/pull/N/head, including fork PRs.