Nominal Code is an AI-powered code review and code fix agent for GitHub and GitLab pull requests. It uses Claude to read your diffs, post structured inline reviews, and optionally push fixes — all without leaving your PR.

It runs anywhere: as a CI job (GitHub Actions or GitLab CI), from the command line, or as a self-hosted webhook server for real-time interaction.

What it does

Nominal Code ships two bots, each with a distinct role:

	Reviewer	Worker
Purpose	Posts structured inline code reviews	Applies code changes and pushes commits
Tool access	Read-only (safe to run on any PR)	Full (clones, edits, commits, pushes)
Output	Review comments anchored to specific diff lines	Commits pushed to the PR branch

Both bots accept a custom prompt to steer the review (e.g. "focus on security" or "check for SQL injection"), and respect per-repo coding guidelines placed in .nominal/ at the root of your repository.

How to run it

CI job

The fastest way to get started. The example below uses GitHub Actions — GitLab CI is also supported (see Configuration).

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

You can also pass model, max_turns, prompt, and coding_guidelines as inputs.

CI mode calls the Anthropic API directly and does not require the Claude Code CLI.

CLI

Run a one-off review on any PR without deploying anything:

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 --dry-run
uv run nominal-code review owner/repo#42 --prompt "focus on security"

Supports --platform, --model, and --max-turns. Works with GitLab too (--platform gitlab).

Webhook server

For teams that want real-time interaction — mention the bot in a PR comment and it responds:

cd nominal-code/app && uv sync

export REVIEWER_BOT_USERNAME=my-reviewer
export ALLOWED_USERS=alice,bob
export GITHUB_TOKEN=ghp_...
export GITHUB_WEBHOOK_SECRET=your-secret

uv run nominal-code

The server supports GitHub App authentication as an alternative to PATs, auto-triggering reviews on PR lifecycle events, and multi-turn conversations that carry context across comments. See Getting Started for the full setup.

Configuration highlights

What	How
Claude model	AGENT_MODEL env var, --model flag, or model Action input
Review prompt	--prompt flag, INPUT_PROMPT env var, or prompt Action input
Coding guidelines	Global via CODING_GUIDELINES, per-repo via .nominal/guidelines.md
Language-specific rules	prompts/languages/ or .nominal/languages/{lang}.md per repo
Auto-trigger	REVIEWER_TRIGGERS=pr_opened,pr_push,pr_reopened,pr_ready_for_review
Allowed users	ALLOWED_USERS=alice,bob (webhook mode)

Full reference: Configuration

Documentation

• Getting Started — from zero to a working bot
• CLI Mode — one-off reviews without a server
• Configuration — environment variables and options
• Architecture — request flow, agent runners, workspace layout
• Deployment — production setup, Docker, health checks
• Platforms: GitHub | GitLab
• Bots: Reviewer | Worker

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

• Only users in ALLOWED_USERS can trigger the bots — other comments are silently ignored
• Webhook signatures are verified when secrets are configured
• GitHub App auth provides auto-rotating installation tokens
• The reviewer bot is restricted to read-only tools; the worker bot has full access