Automated code reviews posted inline on your pull requests — GitHub and GitLab, any LLM provider, scales from solo dev to org-wide Kubernetes deployment.

---

Nominal Code reads your PR diffs, runs an AI agent with read-only access to the repository, and posts structured inline reviews anchored to specific lines of code. It works as a CI job, a CLI command, or a self-hosted webhook server with real-time interaction.

Key Features

• Inline reviews on real diff lines — not just a wall of text. Comments land exactly where the issue is, like a human reviewer.
• 7 LLM providers or Claude Code CLI — use any provider API (Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, Together, Fireworks), or run via the Claude Code CLI with a Pro/Max subscription — no API key needed.
• GitHub + GitLab — same bot, both platforms simultaneously. GitHub App and PAT authentication supported.
• Multi-turn conversations — mention the bot again and it remembers the full PR discussion (webhook mode).
• Custom prompts and per-repo guidelines — steer reviews with instructions like "focus on security", or drop a .nominal/guidelines.md in your repo for persistent rules.
• Language-aware — automatically applies language-specific guidelines when the diff contains Python, Go, TypeScript, etc.
• Auto-trigger or @mention — run reviews automatically on PR open, push, reopen, or ready-for-review events, or trigger them on demand by mentioning the bot in a comment.
• Scales to any org size — runs as a single process for small teams, or deploy to Kubernetes where each review runs as an isolated Job with automatic queuing and horizontal scaling.
• YAML config — one structured file for all settings. Environment variables as overrides for secrets and runtime tuning.

Get Started in 60 Seconds

Add your API key as a repository secret, then create a workflow file:

# .github/workflows/review.yml
name: Code Review
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: gauthierdmn/nominal-code@main
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

Open a pull request — the review runs automatically. Pass provider and the matching API key to use a different LLM. See CI Mode for all provider examples and GitLab CI setup.

All the Ways to Run It

Mode	Best for	What happens
CI	Easiest setup	Runs in GitHub Actions or GitLab CI on every PR event
CLI	One-off reviews	uv run nominal-code review owner/repo#42 from your terminal
Webhook	Teams	Self-hosted server with @mention triggers and multi-turn conversations
Kubernetes	Production scale	Webhook server dispatches each review as a K8s Job

CLI

cd nominal-code/app && uv sync
export GITHUB_TOKEN=ghp_...

uv run nominal-code review owner/repo#42
uv run nominal-code review owner/repo#42 --prompt "focus on security"
uv run nominal-code review owner/repo#42 --dry-run

Webhook Server

cd nominal-code/app && uv sync

# config.yaml
# reviewer:
#   bot_username: "my-reviewer"
#   triggers: [pr_opened]
# access:
#   allowed_users: [alice, bob]

export GITHUB_TOKEN=ghp_...
export GITHUB_WEBHOOK_SECRET=your-secret
export CONFIG_PATH=config.yaml

uv run nominal-code serve

Mention @my-reviewer in a PR comment — the bot responds with a structured review. Supports GitHub App auth, auto-triggering, and multi-turn conversations that carry context across comments.

Configuration

Nominal Code uses a YAML config file as the primary configuration method. Environment variables always override the YAML file — use them for secrets and runtime tuning.

# config.yaml
reviewer:
  bot_username: "my-reviewer"
  triggers:
    - pr_opened
    - pr_push

agent:
  provider: "anthropic"
  model: "claude-sonnet-4-6"

access:
  allowed_users:
    - alice
    - bob
  allowed_repos:
    - myorg/backend
    - myorg/frontend

Full reference: Configuration | Environment Variables

Documentation

• Getting Started — from zero to a working review
• Modes: CI | CLI | Webhook
• Platforms: GitHub | GitLab
• Bots: Reviewer | Worker (Beta)
• Reference: Configuration | Environment Variables
• Architecture | Deployment | Security

Development

cd app && uv sync

uv run ruff check nominal_code/ tests/
uv run ruff format nominal_code/ tests/
uv run mypy nominal_code/
uv run pytest

Security

Nominal Code includes webhook signature verification, tool restrictions, token separation, and resource limits. See Security for the full trust model and hardening recommendations.