Skip to documentation

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.

Terminal
gh auth login
gh extension install cli/gh-webhook
gh auth status

2. Install review-relay

$ curl -fsSL https://github.com/Tyru5/review-relay/releases/latest/download/install.sh | bash

Standalone 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

Terminal
review-relay setup
review-relay start -d
review-relay tui

setup 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 an open PR
review-relay run --repo acme/widget --pr 42

No 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.

~/.review-relay/config.json · example
{
  "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

Top-level configuration options
OptionDefaultWhat it does
reposRequiredNon-empty list of GitHub repositories and their local clones.
port9988Local webhook server port, 1 to 65535; 0 picks a free one. Listens on 127.0.0.1 only.
graceMs120000In auto mode, wait this many milliseconds for Greptile or CodeRabbit before the GitHub fallback runs.
timeoutMs1800000Per-reviewer timeout in milliseconds. The default is 30 minutes.
maxConcurrent2Reviews 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.
modelsBuilt-in entriesModel, 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-relayReports, 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.

Repository configuration options
OptionDefaultWhat it does
fullNameRequiredGitHub owner/name, for example acme/widget.
localPathRequiredExisting local clone with an origin remote for this repository. ~/ expands to your home. Relative paths resolve from the process working directory.
triggerautoauto, greptile, coderabbit, or github. Mentions work in every mode.
postToPrtruePublish the report as a PR comment. Set false for local reports only; reviewers still run.
statusfalsetrue 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.
inlineCommentsfalseAlso 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.onPushfalseAlso handle pull_request.synchronize when new commits are pushed. Applies to github and auto modes.
github.mention@review-relayCase-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.
Use a different config
review-relay info --config ./relay.json
review-relay start -d --config ./relay.json

Use 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
Environment variables
OptionDefaultWhat it does
REVIEW_RELAY_CONFIG~/.review-relay/config.jsonConfig path for the CLI and installers. --config takes precedence in the CLI.
REVIEW_RELAY_DEBUGNot setAny non-empty value logs why webhook events were ignored. Set before starting the daemon.
NO_COLORNot setA non-empty value disables CLI color, even if FORCE_COLOR is set.
FORCE_COLORNot setA non-empty value other than 0 enables CLI color.
REVIEW_RELAY_INSTALL_VERSIONlatestInstaller release version. Unix --version and PowerShell -Version take precedence.
REVIEW_RELAY_INSTALL_BIN_DIRPlatform defaultInstaller destination. Unix --bin-dir and PowerShell -BinDir take precedence.
REVIEW_RELAY_INSTALL_REPOTyru5/review-relayGitHub repo to download releases from. Only use a repo you trust.
REVIEW_RELAY_INSTALL_NO_MODIFY_PATHNot setWindows only. Any non-empty value prevents PATH changes; equivalent to -NoModifyPath.
REVIEW_RELAY_INSTALL_NO_ALIASNot setAny 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.

Supported reviewers
Reviewer IDProductRelay defaults
claudeClaude Codeclaude-opus-5-5, effort max
codexCodex CLIgpt-6-astra, effort high
auggieAugment AuggieCLI default model; effort supported
copilotGitHub Copilot CLICLI default model; effort supported
droidFactory DroidCLI default model; effort supported
geminiGemini CLICLI default model; no per-run effort option
grokGrok BuildCLI default model; effort supported
hermesHermes AgentCLI default model; effort supported
kiloKilo Code CLICLI default model; effort supported
opencodeopencodeCLI default model; effort supported
pipiCLI default model; effort supported
qwenQwen CodeCLI default model; no per-run effort option
vibeMistral VibeCLI 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

Model entry options
OptionDefaultWhat it does
harnessRequired for custom IDsOne of the supported CLI IDs below. A built-in ID always uses its own CLI.
labelCLI label or custom IDName shown in the PR comment. Active reviewer labels must be unique, ignoring case.
modelHarness defaultModel identifier accepted by the CLI. Omit to use the relay default below, or the CLI default when none is set.
effortHarness defaultReasoning setting for CLIs that support it. Model and CLI versions determine which values work.
providerNot setHermes 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.

Routed config · example
{
  "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

Route options
OptionDefaultWhat it does
nameRequiredUnique ID, up to 32 lowercase letters, digits, and dashes; starts with a letter or digit.
whenRequiredNon-empty object of conditions below. All conditions must match.
reviewersEither reviewers or skipNon-empty list of known reviewer IDs, without duplicates. Replaces the fallback panel.
skipOmit for review routesSet true instead of reviewers to skip. Skip routes cannot set timeoutMs.
timeoutMsGlobal timeoutMsPositive 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.

Route match conditions
ConditionValueMatches when
reposGlob listMatch owner/name, ignoring case. Each pattern must match at least one configured repo.
baseBranchesGlob listMatch the target branch, not the PR head branch. Case-sensitive.
sourcesValue listgreptile, coderabbit, github, mention, manual, or local.
pathsGlob listAt least one changed path matches. Includes the old path of a renamed file.
onlyPathsGlob listEvery changed path must match at least one pattern, including both sides of renames. Empty diffs do not match.
minLinesInteger ≥ 0Minimum additions + deletions, inclusive, excluding recognized lockfiles.
maxLinesInteger ≥ 0Maximum additions + deletions, inclusive, excluding recognized lockfiles.
minFilesInteger ≥ 0Minimum number of changed non-lockfiles, inclusive.
maxFilesInteger ≥ 0Maximum number of changed non-lockfiles, inclusive.
wideImpactBooleanMatch 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

PR comment
@review-relay sensitive

A 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

Trigger modes
ModeStarts onBehavior
autoGreptile, CodeRabbit, or GitHubDefault. A Greptile or CodeRabbit start runs immediately. A GitHub PR event waits graceMs, then runs if neither bot has started for that commit.
githubGitHub PR eventsRuns immediately on opened, reopened, and ready_for_review. Add github.onPush: true for synchronize events.
greptileGreptile check startOnly the Greptile start triggers automatic reviews. No GitHub fallback.
coderabbitCodeRabbit review startOnly 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.

  1. Receive an event. Each repo has a temporary webhook forwarded through gh webhook forward to the local signed endpoint. No public relay URL is needed.
  2. 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 maxConcurrent reviews run at once; the rest wait as queued.
  3. 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.
  4. Choose the route. Fetch the PR and base branch, inspect the diff, and select reviewers. A skip stops before a worktree is created.
  5. Run the panel. Create a detached worktree, remove executable project-level agent config, and run the selected CLIs concurrently against the same rubric.
  6. 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.
  7. Report the result. Set the commit status and send notifications, when configured. The status went pending when 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 commit HEAD was at, so you can keep working while it runs. Follow it in review-relay tui or review-relay logs -f.
Score the current branch
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 (default HEAD) that --base lacks. The base defaults to the remote’s default branch as the clone recorded it (origin/HEAD), else origin/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 fetch first 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.
review options
OptionDefaultWhat it does
-d, --detachForegroundReview in the background and return at once. Follow it in tui or logs -f.
--base <ref>origin/HEAD, else origin/mainRef to diff against. Any ref works: a remote branch, a local branch, or a SHA.
--head <ref>HEADRef to review. Uncommitted changes are only checked, and left out, when this is HEAD.
--route <name>Normal routingUse this non-skip route instead of the one the branch matches.
--reviewers <ids>Normal routingComma-separated reviewer IDs to run instead of routing. Not with --route.
--min-score <n>NoneExit 1 when the confidence is under n, from 1 to 5. Foreground only.
--jsonOffPrint 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.

Repo and top-level settings · example
{
  "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.

notify options
OptionDefaultWhat it does
on["low","failed"]done: every finished review. low: confidence under minScore. failed: the review failed, or every reviewer did.
minScore4The threshold for low, from 1 to 5.
desktopfalsemacOS osascript, Linux notify-send, or a Windows toast; on WSL without notify-send, the Windows toast.
ntfyNoneAn ntfy topic URL. Gets the text, with Title, Tags, and Click headers.
slackNoneA Slack incoming webhook URL. Gets { text }.
webhookNoneAny URL. Gets JSON: event, repo, pr, branch, local, headSha, score, findings by severity, reviewers, url, error, title, text.

Pre-push hook

Score every push
review-relay hook install
review-relay hook install --min-score 3
review-relay hook uninstall

hook 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.

Register the server
claude mcp add review-relay -- review-relay mcp    # Claude Code
codex mcp add review-relay -- review-relay mcp     # Codex

Other clients take the same command in their MCP config. Add --config <path> to the arguments for a config other than the default.

MCP config · other clients
{
  "mcpServers": {
    "review-relay": {
      "command": "review-relay",
      "args": [
        "mcp"
      ]
    }
  }
}

Tools

MCP tools
ToolArgumentsWhat it does
review_branchpath, base, head, route | reviewers, waitSecondsStart 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_prrepo, pr, route, waitSecondsStart 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_reviewkey | repo + pr | none, waitSecondsA 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_reviewsrepo, pr, status, limitRecent 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 key at once and a separate process runs the review, as review -d does. Until that process records the job, its status is starting.
  • Wait when you want to. waitSeconds, up to 600 on the start tools and get_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, so status, cost, and tui show them, and their output goes to daemon.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.

CLI commands
CommandArguments / optionsPurpose
setupNo required flagsInteractive repo and reviewer selection. Writes the config and preserves settings it does not ask about.
start-d, --detachWatch repos. Foreground by default; -d runs in the background and writes daemon.log.
stopNo flagsStop the background daemon. Attempts graceful shutdown, then forces exit after 20 seconds.
restartNo flagsStop, then start in the background. Use after editing config.
instances--jsonRemote 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.
tuiNo flagsLive 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, --followRead 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.
hookinstall [--min-score <n>] [--base <ref>] [--route <name> | --reviewers <ids>] | uninstallWrite 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.
mcpNo flagsMCP 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--jsonResolved configuration and diagnostics. --json prints machine-readable output.
config[edit|check] --json --strictPrint 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

Full-screen job view
review-relay tui

tui 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 -.

TUI keys
KeyWhereWhat it does
enterJob listOpen the job: scores, findings, and the posted comment, or its log lines while it runs.
[ ]JobSelect the previous or next Details or Dimension notes section; enter or space expands or collapses it.
← →AnyPan a table or line wider than the screen. They only pan, and stop at the edges.
lAnyFollow the job’s lines from the daemon log as they arrive.
LAnyThe whole daemon log.
iAnyRemote instances and overlap warnings. Requires presence configuration; esc returns to jobs.
/Job listFilter by repo, PR, commit, status, source, route, or error text.
sJob listCycle the status filter: queued, running, done, failed, skipped, superseded, cancelled, all.
rAnyReview the PR, or a local review’s branch, again in the background. Asks first.
cAnyCancel a queued or running review. Asks first; its reviewers stop and nothing is posted.
oAnyOpen the PR in the browser.
yAnyCopy the PR’s URL.
tAnyCycle the theme: dark, light, terminal. Saved to the config without restarting the daemon.
qAnyQuit. 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

Stop a queued or running review
review-relay cancel --repo acme/widget --pr 42
review-relay cancel
review-relay cancel --head feature

With --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

Explain routing without running agents
review-relay route --repo acme/widget --pr 42 --source github

run --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.

Inspect triggers without running agents
review-relay replay events.jsonl --dry-run --grace 0

Dry-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.

Report directory
<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 PR

meta.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.

Judge the reviewers by what the next commit did
review-relay scorecard
review-relay scorecard --repo acme/widget --json

scorecard 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

Costs per review and per reviewer
review-relay cost
review-relay cost --repo acme/widget --pr 42
review-relay cost --json | jq .costUsd

cost 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 cover gpt-6-astra, gpt-6-sol, gpt-6.1-sol, and gpt-6-luna; pricing in 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 cost counts 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

Start with these checks
review-relay status
review-relay info
review-relay logs 100
gh auth status

tui 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.

Back to quick startBack to the landing page