Put your panel to work.

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 status

2. Install review-relay

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

review-relay setup
review-relay start -d
review-relay status

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.

review-relay run --repo acme/widget --pr 42

Use start without -d for foreground logs. The machine and daemon must stay running to receive events.

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

Repository options

Each object in repos accepts these settings. Use an absolute path, or ~/, so the clone resolves consistently.

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.

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.

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

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

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.

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

Mentions work in all three modes. 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, and in-progress jobs suppress duplicates. Failed jobs can retry on another trigger.
3. Choose the route. Fetch the PR and base branch, inspect the diff, and select reviewers. A skip stops before a worktree is created.
4. Run the panel. Create a detached worktree, remove executable project-level agent config, and run the selected CLIs concurrently against the same rubric.
5. Save and publish. Remove the temporary worktree, save reports, and create or update a PR comment if enabled.

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.

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.

Preview or force a route

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, mention, or manual. 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 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; review-relay does not install a merge gate.

<dataDir>/reports/<owner__repo>/pr-<number>/<sha8>/
  comment.md
  <reviewer-id>.json
  meta.json

meta.json records the job, route, selected models, timeouts, durations, and scores. Reviewer JSON contains the verdict, or an error and raw output on failure. Re-running the same PR commit writes to the same directory.

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.

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.

Reports and daemon logs can contain source code and findings. Protect dataDir accordingly. Stop the daemon normally so the forwarders can remove their temporary repository webhooks.

Troubleshooting#

review-relay status
review-relay info
review-relay logs 100
gh auth status

Back to quick startBack to the landing page