A bot that monitors GitHub PRs and GitLab MRs for review comments mentioning it, then uses an AI agent to respond, review code, and otionally push changes. Comment @your-bot fix this bug on a pull request, and the bot clones the repo, runs the agent, and replies with comments and/or code commits.

Features

• Worker bot — receives a prompt, clones the repo, runs an agent with full tool access, commits and pushes changes
• Reviewer bot — fetches the PR diff, runs an agent with read-only tools, posts structured inline code reviews
• CLI mode — run a one-off review on any PR without deploying a webhook server
• GitHub and GitLab — supports both platforms simultaneously
• Session continuity — multi-turn conversations within the same PR
• Automatic cleanup — stale workspaces for closed/merged PRs are removed periodically
• Private dependencies — agents can clone internal libraries for context

Quick Start

CLI Mode (no server required)

git clone https://github.com/gauthierdmn/nominal-code.git
cd nominal-code/app
uv sync

export GITHUB_TOKEN=ghp_...

# Review any PR
uv run nominal-code review owner/repo#42

# Dry run (print results without posting)
uv run nominal-code review owner/repo#42 --dry-run

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

Webhook Server Mode

cd nominal-code/app
uv sync

# Configure (see docs/configuration.md for all options)
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

Documentation

• Getting Started — from zero to a working bot
• CLI Mode — run one-off reviews without a server
• Configuration — full environment variable reference
• Platforms
  • GitHub — webhook setup, tokens, supported events
  • GitLab — webhook setup, self-hosted support, differences from GitHub
• Bots
  • Worker — full-access agent that pushes code changes
  • Reviewer — read-only agent that posts structured reviews
• Architecture — request flow, components, workspace layout
• Deployment — production setup, health checks, reverse proxy

Development

cd app

# Install with dev dependencies
uv sync

# Lint and format
uv run ruff check nominal_code/ tests/
uv run ruff format nominal_code/ tests/

# Type check
uv run mypy nominal_code/

# Run tests
uv run pytest

Security

• Only users listed in ALLOWED_USERS can trigger the agent — comments from other users are silently ignored
• Webhook signatures are verified when secrets are configured
• The worker bot runs with full tool access (bypassPermissions)
• The reviewer bot is restricted to read-only tools (Read, Glob, Grep, Bash(git clone*))