code-reviewer

AI-powered code review CLI for GitHub pull requests and GitLab merge requests. Uses Vertex AI (Gemini, Claude, Mistral) or any OpenAI-compatible endpoint to analyze diffs and post actionable findings as inline comments.

Install

# Homebrew
brew install OpticDiff/tap/code-reviewer

# Nix
nix run github:OpticDiff/code-reviewer
nix profile install github:OpticDiff/code-reviewer

# mise
mise use -g ubi:OpticDiff/code-reviewer

# Go
go install github.com/OpticDiff/code-reviewer/cmd/code-reviewer@latest

# Pre-built binary from GitHub Releases
# https://github.com/OpticDiff/code-reviewer/releases

# Build from source
git clone https://github.com/OpticDiff/code-reviewer.git
cd code-reviewer && go build -o code-reviewer ./cmd/code-reviewer

Features

Incremental review — Only review files changed in the latest push, not the entire MR (v0.3.0)
SARIF output — Write findings in SARIF 2.1.0 format for CI security tabs (v0.3.0)
Multi-model consensus — Run multiple models in parallel (e.g. Gemini + Claude), only keep findings that meet the configured consensus threshold
Custom prompts — Bring your own system prompt for specialized reviews (security audits, architecture checks)
Focus modes — bugs, security, performance, style, docs, or all
Severity filtering — low (default), medium, high, critical
Rich terminal output — ANSI-colored findings with severity badges, file grouping, and suggestion blocks
GitLab integration — Inline diff discussions or simple MR notes, with idempotent cleanup on re-push
Context-aware — Modular chunking strategies for large MRs
Repo-aware context — Tree-sitter extracts changed symbols from diffs; grep finds usages in unchanged files to give the reviewer cross-file awareness
REVIEW.md — Drop a REVIEW.md in your repo root to inject team-specific review instructions at the highest priority
Auto-summary — --summarize generates structured MR descriptions from diffs: classification, intent, risk level, scope areas, and breaking changes
Intent-aware review — --intent enables two-pass review: infer intent, then review against it. Auto-enabled in CI (v0.5.0)
Explain mode — --explain generates a plain-language walkthrough of the diff (v0.5.0)
Fix mode — --fix applies suggested code fixes directly to the working tree (v0.5.0)
Pre-push hook — code-reviewer hook install sets up automatic review before git push (v0.5.1)
Configurable — CLI flags, env vars, per-repo .code-reviewer.yaml, or REVIEW.md
GitHub support — Full PR review integration: inline comments, code suggestions, previous review cleanup (v0.6.0)
Code suggestions — AI-generated fix suggestions rendered as platform-native suggestion blocks (v0.6.0)
Multi-line comments — Findings can span line ranges for more precise feedback (v0.6.0)
Description update — --update-description injects review summary into MR/PR description with idempotent markers (v0.6.0)
Review cleanup — --cleanup-mode controls how previous bot reviews are handled: delete (default) or resolve (v0.6.0)
GitLab Draft Notes — Reviews posted as draft notes and published atomically for a single notification (v0.6.0)

Quick Start

Local Usage

# Review your branch against origin/HEAD (colored terminal output)
export GOOGLE_CLOUD_PROJECT=my-gcp-project
code-reviewer --diff

# Review against a specific ref
code-reviewer --diff HEAD~3

# Review specific files
code-reviewer --files internal/handler.go,internal/service.go

# Security-focused review with a custom prompt
code-reviewer --diff --focus security --custom-prompt examples/prompts/security-audit.md

# Only show high/critical issues
code-reviewer --diff --min-severity high

# JSON output for tooling integration
code-reviewer --diff --json

# SARIF output for CI security tabs (GitLab, GitHub)
code-reviewer --diff --sarif results.sarif

# Disable colors (or set NO_COLOR env var)
code-reviewer --diff --no-color

GitLab CI

Add to your .gitlab-ci.yml:

# Quick setup — uses CI_JOB_TOKEN, no PAT needed
code-review:
  stage: review
  image: gcr.io/$PROJECT/code-reviewer:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    GITLAB_TOKEN: $CI_JOB_TOKEN
    REVIEW_COMMENT_MODE: "notes"
    SARIF_OUTPUT: "results.sarif"
  script:
    - code-reviewer --ci --incremental
  allow_failure: true
  artifacts:
    reports:
      sast: results.sarif
    when: always

For inline diff-anchored comments, use a Project Access Token with api scope:

code-review:
  variables:
    GITLAB_TOKEN: $CODE_REVIEWER_TOKEN    # PAT with api scope
    REVIEW_COMMENT_MODE: "discussions"
  script:
    - code-reviewer --ci

See .gitlab-ci.example.yml for the full setup.

GitHub Actions

Add to .github/workflows/code-review.yml:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SA }}

      - name: Install code-reviewer
        run: go install github.com/OpticDiff/code-reviewer/cmd/code-reviewer@v0.6.0

      - name: Review PR
        env:
          GOOGLE_CLOUD_PROJECT: ${{ secrets.GCP_PROJECT }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: code-reviewer --ci

The GITHUB_TOKEN is provided automatically by GitHub Actions. The tool detects the GitHub environment and posts review comments on the PR.

Configuration

Settings are applied in priority order: CLI flags > env vars > .code-reviewer.yaml > defaults.

CLI Flags

Flag	Description	Default
`--ci`	Run in CI mode (auto-detects GitHub/GitLab)	—
`--diff [ref]`	Review local git diff	`origin/HEAD`
`--files f1,f2`	Review specific files	—
`--model`	Vertex AI model ID	`gemini-2.5-flash`
`--models`	Comma-separated models for multi-model consensus	—
`--consensus-threshold`	Min models that must agree on a finding	`2` (when `--models` is set)
`--focus`	Review focus (comma-separated)	`all`
`--min-severity`	Minimum severity to report	`low`
`--comment-mode`	`notes` or `discussions`	`notes`
`--chunk-strategy`	`fail` or `split`	`fail`
`--extra-rules`	Additional prompt rules	—
`--custom-prompt`	Path to custom system prompt file	—
`--dry-run`	Analyze without posting	`false`
`--json`	Output results as JSON	`false`
`--sarif`	Write SARIF 2.1.0 output to file	—
`--no-color`	Disable ANSI color output	`false`
`--no-context`	Disable repo-aware cross-file context injection	`false`
`--max-tokens`	Maximum total tokens per review (0 = unlimited)	`0`
`--api-url`	OpenAI-compatible API endpoint (e.g., `http://localhost:11434/v1`)	—
`--api-key`	API key for HTTP provider (optional for IAM/ADC auth)	—
`--incremental`	Only review files changed in latest push (CI mode)	`false`
`--proxy-url`	Route model calls through an LLM proxy (e.g. Candela)	—
`--summarize`	Generate structured MR summary instead of review	`false`
`--summary-update-description`	Update MR description with generated summary	`false`
`--intent`	Enable two-pass intent-aware review	`false` (auto in CI)
`--no-intent`	Disable intent-aware review (overrides CI default)	`false`
`--explain`	Explain the diff instead of reviewing it	`false`
`--fix`	Apply suggested fixes to the working tree	`false`
`--update-description`	Inject review summary into MR/PR description	`false`
`--cleanup-mode`	How to handle previous reviews: `delete` or `resolve`	`delete`
`--version`	Print version and exit	—
`hook install`	Install a pre-push git hook	—
`hook uninstall`	Remove the pre-push git hook	—

Environment Variables

Variable	Description	Default
`GOOGLE_CLOUD_PROJECT`	GCP project for Vertex AI	Required
`GOOGLE_CLOUD_LOCATION`	GCP region	`us-central1`
`GITLAB_TOKEN`	GitLab API token	Required in CI
`GITLAB_BASE_URL`	GitLab API base URL	`https://gitlab.com`
`REVIEW_MODEL`	Model ID	`gemini-2.5-flash`
`REVIEW_MODELS`	Comma-separated models for consensus	—
`REVIEW_FOCUS`	Focus areas	`all`
`REVIEW_MIN_SEVERITY`	Min severity	`low`
`REVIEW_COMMENT_MODE`	Comment mode	`notes`
`REVIEW_CHUNK_STRATEGY`	Chunk strategy	`fail`
`REVIEW_CUSTOM_PROMPT`	Path to custom system prompt	—
`REVIEW_OUTPUT_JSON`	Output results as JSON (`true`/`false`)	`false`
`SARIF_OUTPUT`	Write SARIF output to this file path	—
`INCREMENTAL`	Only review changed files in latest push (`true`/`false`)	`false`
`EXCLUDED_PATTERNS`	Glob patterns to skip	`go.sum,.lock,vendor/`
`REVIEW_MAX_TOKENS`	Maximum total tokens per review (0 = unlimited)	`0`
`REVIEW_API_URL`	OpenAI-compatible API endpoint	—
`REVIEW_API_KEY`	API key for HTTP provider	—
`NO_COLOR`	Disable ANSI colors (no-color.org)	—
`GITHUB_TOKEN`	GitHub API token (auto-set in GitHub Actions)	Required for GitHub
`CODE_REVIEWER_UPDATE_DESCRIPTION`	Update MR/PR description with summary	`false`
`CODE_REVIEWER_CLEANUP_MODE`	Previous review cleanup mode	`delete`

Per-Repo Config

Create .code-reviewer.yaml in your repo root:

model: gemini-2.5-flash
focus: [bugs, security]
min_severity: low
comment_mode: discussions
custom_prompt: prompts/team-rules.md
excluded_patterns:
  - "*.pb.go"
  - "generated/*"
extra_rules: |
  Always flag raw SQL string concatenation.
  Check that zerolog is used instead of log/fmt.
max_tokens: 50000  # Optional: cap total tokens per review
api_url: http://localhost:11434/v1  # Optional: use a self-hosted model
update_description: false  # Inject summary into MR/PR description
cleanup_mode: delete       # delete or resolve

See .code-reviewer.example.yaml for all options.

Self-Hosted Models

Use --api-url to point at any OpenAI-compatible endpoint. No GCP project required.

# Ollama (local)
code-reviewer --diff --api-url http://localhost:11434/v1 --model qwen3:32b

# Gemma on Cloud Run
code-reviewer --diff --api-url https://gemma-review-xyz.run.app/v1 --model gemma-3-27b

# vLLM
code-reviewer --diff --api-url http://gpu-server:8000/v1 --model meta-llama/Llama-4-Scout-17B-16E

# With Candela proxy (observability + routing)
code-reviewer --diff --api-url http://candela:8080/v1 --model gemini-2.5-flash

REVIEW.md

Create a REVIEW.md in your repo root to inject team-specific review instructions. Its contents are treated as the highest priority instruction in the system prompt — above the built-in rules, focus overlays, and extra rules.

## Our Review Standards

- All exported functions MUST have doc comments.
- Never use `fmt.Errorf` without `%w` for wrapping.
- Prefer table-driven tests over sequential assertions.
- Flag any use of `context.TODO()` — replace with a real context.

The file is discovered by walking up from the working directory, the same way .code-reviewer.yaml is found. Presence is logged at startup (review_md=true).

Repo-Aware Context

By default, code-reviewer uses Tree-sitter (pure-Go, no CGo) to extract symbols defined or modified in the diff, then searches the rest of the repo for usages of those symbols in unchanged files. The matched snippets are injected into the prompt as Related Unchanged Code, giving the model cross-file awareness without sending the entire repo.

Supported languages: Go, Kotlin, Java, Python, TypeScript.

Noise mitigation is built in:

Symbol names shorter than 4 characters are skipped.
If a symbol appears in more than 20 files, it is treated as too common and excluded.
Import statements and comments are filtered out.

Disable with --no-context or the disable_context: true config field.

Auto-Summary

Use --summarize to generate a structured MR description from the diff instead of a code review. The model analyzes the changes and produces:

Classification — feat, fix, refactor, chore, docs, test, security, config, perf
Intent — What the developer is trying to accomplish
Risk level — low, medium, high based on scope, complexity, and sensitivity
Scope areas — Which parts of the codebase are affected (e.g. auth, api, database)
Breaking changes — Any backward-incompatible changes

# Local: summarize your branch diff
code-reviewer --summarize --diff

# CI: post summary as MR comment
code-reviewer --summarize --ci

# JSON output for scripting
code-reviewer --summarize --diff --json

Pre-push Hook

Automatic code review before every push — catches issues before CI, before MR creation, before anyone sees your code.

# Install the hook (one-time setup)
code-reviewer hook install

# Now every git push triggers a review:
$ git push
🔍 code-reviewer: reviewing changes before push...

  ❌ HIGH  internal/auth/handler.go:58
           Nil pointer dereference — token is used before nil check

🚫 Push blocked: 1 HIGH severity finding. Fix or --no-verify to skip.

# Remove the hook
code-reviewer hook uninstall

Honors Git's core.hooksPath configuration. Won't overwrite foreign hooks.

Also works with the pre-commit framework:

# .pre-commit-config.yaml
- repo: https://github.com/OpticDiff/code-reviewer
  rev: v0.6.0
  hooks:
    - id: code-review
      stages: [pre-push]
      args: [--min-severity, high]

Models

All models are accessed via Vertex AI using Application Default Credentials (ADC). No separate API keys needed.

Model	Flag Value	Best For
Gemini 2.5 Flash	`gemini-2.5-flash`	Fast CI reviews (default)
Gemini 2.5 Pro	`gemini-2.5-pro`	Deep analysis
Claude Sonnet 4	`claude-sonnet-4`	Code-focused reviews
Mistral Medium	`mistral-medium-3`	Alternative perspective

Multi-Model Consensus

Run multiple models in parallel and only keep findings that multiple models agree on — dramatically reducing false positives:

# Run Gemini + Claude, keep findings both agree on
code-reviewer --diff --models gemini-2.5-flash,claude-sonnet-4

# Require all 3 models to agree
code-reviewer --diff --models gemini-2.5-flash,gemini-2.5-pro,claude-sonnet-4 --consensus-threshold 3

Findings are deduplicated by file + category + line proximity (±3 lines). The finding with the most detailed explanation is kept as the canonical result.

Custom Prompts

Replace the built-in system prompt with your own for specialized reviews:

code-reviewer --diff --custom-prompt path/to/my-prompt.md

The custom prompt replaces the built-in base prompt, but focus overlays (--focus) and extra rules (--extra-rules) are still appended automatically.

Example Prompts

Four example prompts are included in examples/prompts/:

Prompt	Use Case
`security-audit.md`	Deep security review: injection, auth, crypto, PII
`strict.md`	Zero-tolerance review that flags everything
`quick.md`	Fast review focused only on critical/high issues
`architecture.md`	Architecture and design pattern review

Writing Custom Prompts

A custom prompt is a Markdown file with instructions for the AI reviewer. It should include:

Persona — who the reviewer should act as
Objective — what to focus on
Output format — must instruct the model to return JSON matching the findings schema

See the example prompts for reference.

Auth

Vertex AI (Model)

Uses Application Default Credentials:

# Local development
gcloud auth application-default login

# CI/CD — use Workload Identity Federation or a service account key

GitLab API

Token Type	Capabilities	Setup
`CI_JOB_TOKEN`	Notes API (simple comments)	Automatic, zero config
Project Access Token	Notes + Discussions API (inline diff)	Settings → Access Tokens, `api` scope

GitHub API

Token Type	Capabilities	Setup
`GITHUB_TOKEN` (Actions)	PR review comments, suggestions	Automatic in GitHub Actions
Personal Access Token	PR reviews outside CI	`repo` scope required

Context Window Handling

Large MRs may exceed the model's context window. The --chunk-strategy flag controls behavior:

fail (default) — Errors with a helpful message if the diff is too large. Forces teams to scope MRs.
split — Auto-splits diffs into file groups, runs separate model calls, merges results.

The chunker interface is modular — custom strategies can be added.

Security

Input validation — Diff refs and file paths are validated to prevent command injection via git arguments.
SSRF protection — GitLab pagination URLs are validated against the configured base URL to prevent token exfiltration.
Prompt injection resistance — The system prompt includes adversarial content detection instructions.

Development

# Enter dev shell
nix develop

# Build
go build ./cmd/code-reviewer

# Test
go test ./... -race -count=1 -cover

# Lint
golangci-lint run

# Check version
./code-reviewer --version

CI runs build, test, and lint as 3 parallel jobs. CodeRabbit provides automated PR reviews on GitHub.

Releasing

Releases are automated via GoReleaser. Tag a version to publish binaries to GitHub Releases:

git tag -a v0.6.0 -m "v0.6.0"
git push origin v0.6.0
# → GitHub Actions: test → build 6 binaries → publish to Releases

License

Apache 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 151 Commits
.github		.github
cmd/code-reviewer		cmd/code-reviewer
docs		docs
examples/prompts		examples/prompts
internal		internal
scripts		scripts
.code-reviewer.example.yaml		.code-reviewer.example.yaml
.coderabbit.yaml		.coderabbit.yaml
.gitignore		.gitignore
.gitlab-ci.example.yml		.gitlab-ci.example.yml
.goreleaser.yaml		.goreleaser.yaml
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
REVIEW.md		REVIEW.md
ROADMAP.md		ROADMAP.md
flake.lock		flake.lock
flake.nix		flake.nix
go.mod		go.mod
go.sum		go.sum

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

code-reviewer

Install

Features

Quick Start

Local Usage

GitLab CI

GitHub Actions

Configuration

CLI Flags

Environment Variables

Per-Repo Config

Self-Hosted Models

REVIEW.md

Repo-Aware Context

Auto-Summary

Pre-push Hook

Models

Multi-Model Consensus

Custom Prompts

Example Prompts

Writing Custom Prompts

Auth

Vertex AI (Model)

GitLab API

GitHub API

Context Window Handling

Security

Development

Releasing

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

code-reviewer

Install

Features

Quick Start

Local Usage

GitLab CI

GitHub Actions

Configuration

CLI Flags

Environment Variables

Per-Repo Config

Self-Hosted Models

REVIEW.md

Repo-Aware Context

Auto-Summary

Pre-push Hook

Models

Multi-Model Consensus

Custom Prompts

Example Prompts

Writing Custom Prompts

Auth

Vertex AI (Model)

GitLab API

GitHub API

Context Window Handling

Security

Development

Releasing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages