{"id":46293210,"url":"https://github.com/gauthierdmn/nominal-code","last_synced_at":"2026-04-19T07:02:14.247Z","repository":{"id":340707078,"uuid":"1166975393","full_name":"gauthierdmn/nominal-code","owner":"gauthierdmn","description":"AI bots that review PRs and push code fixes.","archived":false,"fork":false,"pushed_at":"2026-03-04T07:03:25.000Z","size":5345,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T13:20:05.308Z","etag":null,"topics":["ai","ai-agents","claude","code-review","github-bot","gitlab-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gauthierdmn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T20:15:10.000Z","updated_at":"2026-03-04T06:52:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gauthierdmn/nominal-code","commit_stats":null,"previous_names":["gauthierdmn/nominal-code"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gauthierdmn/nominal-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gauthierdmn%2Fnominal-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gauthierdmn%2Fnominal-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gauthierdmn%2Fnominal-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gauthierdmn%2Fnominal-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gauthierdmn","download_url":"https://codeload.github.com/gauthierdmn/nominal-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gauthierdmn%2Fnominal-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30327538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","claude","code-review","github-bot","gitlab-bot"],"created_at":"2026-03-04T09:00:32.809Z","updated_at":"2026-04-19T07:02:14.238Z","avatar_url":"https://github.com/gauthierdmn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/nominal-code-banner.png\" alt=\"Nominal Code\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/gauthierdmn/nominal-code/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/gauthierdmn/nominal-code/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://gauthierdmn.github.io/nominal-code/\"\u003e\u003cimg src=\"https://github.com/gauthierdmn/nominal-code/actions/workflows/docs.yml/badge.svg\" alt=\"Docs\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/release/python-3130/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.13-blue.svg\" alt=\"Python 3.13\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License: Apache 2.0\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Automated code reviews posted inline on your pull requests — GitHub and GitLab, any LLM provider, scales from solo dev to org-wide Kubernetes deployment.\n\u003c/p\u003e\n\n---\n\nNominal Code reads your PR diffs, runs an AI agent with 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.\n\nIn **API mode** (CI, or webhook/CLI with a provider key), a multi-turn reviewer agent investigates the codebase directly and spawns explore sub-agents on demand for deep investigation (callers, test coverage, type hierarchies), then produces findings via structured output. In **CLI mode**, it delegates to the Claude Code CLI which handles exploration and review in one conversation.\n\n## Key Features\n\n- **Agentic review in API mode** — a multi-turn reviewer agent reads annotated diffs and investigates the codebase with Read, Grep, and Glob tools. For deep analysis it spawns explore sub-agents that trace callers, check tests, and verify types — then produces findings with full context. No guessing, no hallucinated line numbers.\n- **Inline reviews with code suggestions** — comments land exactly where the issue is, with one-click-apply fixes.\n- **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.\n- **GitHub + GitLab** — same bot, both platforms simultaneously. GitHub App and PAT authentication supported.\n- **Multi-turn conversations** — mention the bot again and it remembers the full PR discussion (webhook mode).\n- **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.\n- **Language-aware** — automatically applies language-specific guidelines when the diff contains Python, Go, TypeScript, etc.\n- **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.\n- **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.\n- **YAML config** — one structured file for all settings. Environment variables as overrides for secrets and runtime tuning.\n\n## How It Works (API Mode)\n\n```\nPR opened / @mention\n       │\n       v\n  +─────────────────────+\n  │   Reviewer Agent    │    Multi-turn loop (up to 8 turns)\n  │                     │    Tools: Read, Glob, Grep, Bash,\n  │                     │    WriteNotes, submit_review, Agent\n  +──────────+──────────+\n             │\n             ├── [simple lookup] ──\u003e Read / Grep / Glob\n             │\n             ├── [deep investigation] ──\u003e Agent tool\n             │                               │\n             │              +────────────────+────────────────+\n             │              │  Explore sub-agent (32 turns)   │\n             │              │  Read, Glob, Grep, Bash,        │\n             │              │  WriteNotes                     │\n             │              +────────────────+────────────────+\n             │                               │\n             │\u003c── notes content ─────────────+\n             │\n             v\n       submit_review          structured JSON review\n             │\n             v\n      GitHub / GitLab         inline comments + suggestions\n```\n\nIn **CLI mode**, the Claude Code CLI handles both exploration and review in a single multi-turn conversation with its own tool set.\n\n## Get Started in 60 Seconds\n\nAdd your API key as a repository secret, then create a workflow file:\n\n```yaml\n# .github/workflows/review.yml\nname: Code Review\non:\n  pull_request:\n    types: [opened, synchronize, reopened, ready_for_review]\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  review:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: gauthierdmn/nominal-code@main\n        with:\n          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}\n          github_token: ${{ secrets.GITHUB_TOKEN }}\n```\n\nOpen a pull request — the review runs automatically. Pass `provider` and the matching API key to use a different LLM. See [CI Mode](https://gauthierdmn.github.io/nominal-code/modes/ci/) for all provider examples and GitLab CI setup.\n\n## All the Ways to Run It\n\n| Mode | Best for | What happens |\n|---|---|---|\n| [**CI**](https://gauthierdmn.github.io/nominal-code/modes/ci/) | Easiest setup | Runs in GitHub Actions or GitLab CI on every PR event |\n| [**CLI**](https://gauthierdmn.github.io/nominal-code/modes/cli/) | One-off reviews | `uv run nominal-code review owner/repo#42` from your terminal |\n| [**Webhook**](https://gauthierdmn.github.io/nominal-code/modes/webhook/) | Teams | Self-hosted server with `@mention` triggers and multi-turn conversations |\n| [**Kubernetes**](https://gauthierdmn.github.io/nominal-code/deployment/kubernetes/) | Production scale | Webhook server dispatches each review as a K8s Job |\n\n### CLI\n\n```bash\ncd nominal-code/app \u0026\u0026 uv sync\nexport GITHUB_TOKEN=ghp_...\n\nuv run nominal-code review owner/repo#42\nuv run nominal-code review owner/repo#42 --prompt \"focus on security\"\nuv run nominal-code review owner/repo#42 --dry-run\n```\n\n### Webhook Server\n\n```bash\ncd nominal-code/app \u0026\u0026 uv sync\n\n# config.yaml\n# reviewer:\n#   bot_username: \"my-reviewer\"\n#   triggers: [pr_opened]\n# access:\n#   allowed_users: [alice, bob]\n\nexport GITHUB_TOKEN=ghp_...\nexport GITHUB_WEBHOOK_SECRET=your-secret\nexport CONFIG_PATH=config.yaml\n\nuv run nominal-code serve\n```\n\nMention `@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.\n\n## Configuration\n\nNominal Code uses a [YAML config file](https://gauthierdmn.github.io/nominal-code/reference/configuration/#yaml-config-file) as the primary configuration method. Environment variables always override the YAML file — use them for secrets and runtime tuning.\n\n```yaml\n# config.yaml\nreviewer:\n  bot_username: \"my-reviewer\"\n  triggers:\n    - pr_opened\n    - pr_push\n\nagent:\n  provider: \"anthropic\"\n  model: \"claude-sonnet-4-6\"\n\naccess:\n  allowed_users:\n    - alice\n    - bob\n  allowed_repos:\n    - myorg/backend\n    - myorg/frontend\n```\n\nFull reference: [Configuration](https://gauthierdmn.github.io/nominal-code/reference/configuration/) | [Environment Variables](https://gauthierdmn.github.io/nominal-code/reference/env-vars/)\n\n## Documentation\n\n- [Getting Started](https://gauthierdmn.github.io/nominal-code/getting-started/) — from zero to a working review\n- **Modes:** [CI](https://gauthierdmn.github.io/nominal-code/modes/ci/) | [CLI](https://gauthierdmn.github.io/nominal-code/modes/cli/) | [Webhook](https://gauthierdmn.github.io/nominal-code/modes/webhook/)\n- **Platforms:** [GitHub](https://gauthierdmn.github.io/nominal-code/platforms/github/) | [GitLab](https://gauthierdmn.github.io/nominal-code/platforms/gitlab/)\n- [Review Process](https://gauthierdmn.github.io/nominal-code/review/) | [Sub-Agents](https://gauthierdmn.github.io/nominal-code/reference/explore/) | [Compaction](https://gauthierdmn.github.io/nominal-code/reference/compaction/)\n- **Reference:** [Configuration](https://gauthierdmn.github.io/nominal-code/reference/configuration/) | [Environment Variables](https://gauthierdmn.github.io/nominal-code/reference/env-vars/)\n- [Architecture](https://gauthierdmn.github.io/nominal-code/architecture/) | [Deployment](https://gauthierdmn.github.io/nominal-code/deployment/) | [Security](https://gauthierdmn.github.io/nominal-code/security/)\n\n## Development\n\n```bash\ncd app \u0026\u0026 uv sync\n\nuv run ruff check nominal_code/ tests/\nuv run ruff format nominal_code/ tests/\nuv run mypy nominal_code/\nuv run pytest\n```\n\n## Security\n\nNominal Code includes webhook signature verification, tool restrictions, token separation, and resource limits. See [Security](https://gauthierdmn.github.io/nominal-code/security/) for the full trust model and hardening recommendations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgauthierdmn%2Fnominal-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgauthierdmn%2Fnominal-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgauthierdmn%2Fnominal-code/lists"}