Getting Started#

This guide walks through setting up claude-review as a GitHub App that automatically reviews pull requests.

Prerequisites#

• Rust toolchain (stable, 1.85+)

• A GitHub account with permission to create GitHub Apps

• An LLM provider: either an API key (Anthropic, OpenAI, etc.) or a Claude Pro/Max/Team subscription

1. Create a GitHub App#

1. Go to GitHub Settings > Developer settings > GitHub Apps > New GitHub App.

2. Set the following fields:

   • GitHub App name: any unique name (e.g. my-org-code-reviewer)

   • Homepage URL: any URL

   • Webhook URL: your server’s public URL (see step 5), e.g. https://example.com/webhook

   • Webhook secret: generate a strong random string and save it

3. Under Permissions, grant:

   • Pull requests: Read & Write

   • Checks: Read & Write

   • Contents: Read-only

   • Metadata: Read-only

   • Issues: Read & Write (optional — required for @bot review mention triggers)

4. Under Subscribe to events, enable:

   • Pull request

   • Issue comment (optional — only appears after granting Issues permission; needed for [mention_trigger])

5. Click Create GitHub App.

6. Note the App ID shown on the app settings page.

2. Generate a Private Key#

On the GitHub App settings page, scroll to Private keys and click Generate a private key. Save the downloaded .pem file.

3. Write the Configuration#

Create a config.toml file:

[server]
listen = "0.0.0.0:3000"
webhook_path = "/webhook"

[github]
app_id = 123456
private_key_path = "private-key.pem"

[llm]
provider = "claude"
model = "claude-sonnet-4-6"
max_tokens = 4096

[rate_limit]
requests_per_hour = 60
burst = 5

See the Configuration page for all available options.

4. Choose Authentication Method#

Option A: API Key (default)#

Set your LLM API key as an environment variable:

export GITHUB_WEBHOOK_SECRET="your-webhook-secret"
export ANTHROPIC_API_KEY="sk-ant-..."

All supported environment variables:

Option B: Claude Code OAuth (use your subscription)#

If you have a Claude Pro, Max, Team, or Enterprise subscription, you can use it directly without an API key.

1. Set the auth method in your config.toml:

[auth]
method = "oauth"

1. Build the project (see step 5), then run the login flow:

./target/release/claude_review login

This opens your browser to authenticate with Claude. Once authorized, tokens are stored locally at ~/.claude-review/credentials.json and auto-refreshed.

For headless servers without a browser:

./target/release/claude_review login --manual

This prints a URL to visit on any device. After authorizing, paste the code back into the terminal.

To check your auth status:

./target/release/claude_review status

5. Build and Run#

cargo build --release
./target/release/claude_review --config config.toml serve

The serve subcommand is the default, so you can also just run:

./target/release/claude_review --config config.toml

The server starts on the address specified in [server].listen (default 0.0.0.0:3000).

6. Expose the Server#

The webhook endpoint must be reachable from GitHub. For local development, use a tunnel:

# ngrok
ngrok http 3000

# cloudflared
cloudflared tunnel --url http://localhost:3000

Copy the public URL and update the Webhook URL in your GitHub App settings to https://<tunnel-host>/webhook.

7. Install the App#

Go to your GitHub App’s public page and click Install. Select the repositories you want to enable reviews on.

Once installed, every new or updated pull request will trigger an automated review.

Health Check#

The server exposes a GET /health endpoint that returns 200 OK. Use it for load balancer health probes or uptime monitoring.