@bitbean/ai-code-review

AI-powered code review for GitLab merge requests using Anthropic Claude.

Posts review findings as inline threaded discussions directly on your MR diffs.

Setup

Install

npm install @bitbean/ai-code-review

Or run directly in CI with npx:

npx @bitbean/ai-code-review

GitLab CI/CD

Add to your .gitlab-ci.yml:

ai-code-review:
  stage: test
  image: node:26-alpine
  script:
    - npx @bitbean/ai-code-review
  artifacts:
    paths:
      - ai-review-prompts.md
    when: always
    expire_in: 7 days
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

After the pipeline runs, download ai-review-prompts.md from the job artifacts and paste the prompts into Windsurf/Cascade to fix each issue.

Full Example with Custom Artifact Path

stages:
  - review

ai-code-review:
  stage: review
  image: node:26-alpine
  variables:
    REVIEW_ARTIFACT_PATH: "review/fix-prompts.md"
  before_script:
    - mkdir -p review
  script:
    - npx @bitbean/ai-code-review
  artifacts:
    paths:
      - review/fix-prompts.md
    when: always
    expire_in: 30 days
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Configuration

Drop an .ai-review.json in your project root to configure the review behavior. The tool ships with sensible defaults for TypeScript/Node/React projects.

{
  "model": "claude-sonnet-4-6",
  "maxDiffSize": 120000,
  "maxFindings": 7,
  "ignorePatterns": [
    "^package-lock\\.json$",
    "^.*\\/package-lock\\.json$",
    "\\.map$",
    "\\.min\\.",
    "^yarn\\.lock$",
    "^pnpm-lock\\.yaml$"
  ],
  "projectContext": "Describe your project stack and conventions here.\nThe reviewer uses this to avoid false positives.",
  "reviewGuidelines": [
    "Focus on bugs, security issues, performance problems, and significant code quality concerns.",
    "Be concise and actionable — explain *why* something is a problem and *how* to fix it.",
    "Praise particularly elegant or well-thought-out code (sparingly)."
  ],
  "suppressions": [
    "Do not flag missing error handling on RTK Query hooks.",
    "Do not comment on import ordering — this is handled by tooling."
  ]
}

Config Fields

| Field | Type | Description | | ------------------ | ---------- | --------------------------------------------------------------------------------------- | | model | string | Anthropic model to use | | maxDiffSize | number | Skip review if diff exceeds this many chars | | maxFindings | number | Hard cap on findings returned (default: 7) | | ignorePatterns | string[] | Regex patterns for files to skip | | projectContext | string | Project context injected into the system prompt | | reviewGuidelines | string[] | Custom review guidelines (replaces defaults) | | suppressions | string[] | Things the reviewer should NOT flag | | artifactPath | string | Output path for fix-prompts artifact ("" to disable, default: ai-review-prompts.md) |

Priority Order

1. Environment variables (highest — for CI overrides)
2. .ai-review.json in working directory
3. Built-in defaults

Environment Variables

Required

| Variable | Description | | ---------------------- | ---------------------------------- | | ANTHROPIC_API_KEY | Anthropic API key | | GITLAB_TOKEN | GitLab PAT with api scope | | CI_PROJECT_ID | GitLab project ID (auto-set in CI) | | CI_MERGE_REQUEST_IID | MR internal ID (auto-set in CI) |

Optional (override config file)

| Variable | Description | | ------------------------ | ---------------------------------------------------------- | | ANTHROPIC_MODEL | Override model from config | | REVIEW_MAX_DIFF_SIZE | Override max diff size | | REVIEW_IGNORE_PATTERNS | Comma-separated patterns to add to ignore list | | REVIEW_PROJECT_CONTEXT | Override project context entirely | | REVIEW_ARTIFACT_PATH | Override artifact output path ("" to disable) | | CI_API_V4_URL | GitLab API base URL (default: https://gitlab.com/api/v4) |

How It Works

1. Fetches the MR diff from GitLab API
2. Filters out ignored files (lock files, sourcemaps, minified files, plus custom patterns)
3. Sends the diff to Claude for review
4. Writes a fix-prompts artifact (Markdown file with copy-paste-ready prompts for Windsurf/Cascade)
5. Posts a summary note on the MR
6. Posts individual findings as inline discussions on the relevant diff lines
7. Falls back to regular notes when inline positioning fails

Fix Prompts Artifact

The tool outputs an ai-review-prompts.md file (configurable via artifactPath) containing structured fix instructions. Each finding becomes a self-contained prompt you can paste directly into an AI coding assistant like Windsurf, Cursor, or Copilot.

Example output:

# AI Code Review — Fix Prompts

> Generated from MR: **Add user validation**
> Branch: `feature/validation` → `main`
> Findings: 2

## Summary

The MR adds input validation but misses edge cases in the email parser.

---

## Fix Instructions

Paste each prompt below into Windsurf/Cascade (or any AI coding assistant) to resolve the issue.

### 1. [CRITICAL] SQL injection in search query

**File:** `src/api/controllers/users.ts:45`

```text
Fix the following issue in src/api/controllers/users.ts:45:

SQL injection in search query: The search parameter is interpolated directly into the SQL string. Use a parameterized query or Sequelize's `where` clause with `Op.like` instead.
```

### Usage in Windsurf

1. Download the artifact from your GitLab pipeline
2. Open the file and copy a prompt block
3. Paste into Windsurf's chat — it will locate the file and apply the fix
4. Repeat for each finding

## Development

```bash
npm install
npm run lint
npm run build

Run locally (requires env vars set):

npm run review

License

MIT