CodeReviewAgent

An AI reviewer for GitLab merge requests that reads your repository, not just the diff.

One specialist agent per changed file, a real checkout of the branch under review, and a comment pipeline built to post fewer, better findings.

Quickstart · How it works · Configuration · Analytics · Contributing

---

Why another AI reviewer?

Most AI reviewers see a diff and guess. Their most common false positives are exactly the ones a diff produces: "this symbol is undefined" (it is defined in a file the diff does not show), "this method is never implemented", "this variable is unused". Nobody reads the tenth wrong comment.

CodeReviewAgent is built around the opposite assumptions:

• It reads the code. Every reviewer works over a checkout of the merge request's source branch, pinned to the exact commit being reviewed, with read_file, grep and glob. "Is this defined anywhere?" becomes a question it can answer.
• Silence is a valid answer. A reviewer that finds nothing says so. Findings are gated, ranked, de-duplicated and capped before anything reaches the merge request.
• Your conventions, not ours. Which files are reviewed, by whom, and under which house rules is a YAML profile, plus optional instruction files that live in your repository.

What it posts

• Inline findings on the exact diff line, headed with a severity badge (🔴 high · 🟠 medium), with an Apply suggestion button when the fix is concrete code.
• A review summary, once per merge request. It orients the human reviewer (what changed, where to look) and does not repeat the findings.
• Labels: ai-reviewed, plus a review effort::N/5 estimate of how hard the MR is for a human to review.

Re-running on a new push reviews only the commits since the last review, and never re-posts a finding that is already on the merge request.

How it works

 merge request ──► fetch diff (GitLab API) ──► shallow checkout of the source branch
                                                          │
                     review profile (YAML) ──► classify each changed file
                                                          │
                          ┌───────────────────────────────┼───────────────────────────────┐
                    service reviewer                sql reviewer                   test reviewer   …
                   (read · grep · glob)          (read · grep · glob)          (read · grep · glob)
                          └───────────────────────────────┼───────────────────────────────┘
                                                          ▼
      in-diff gate ─► rank & purge false positives ─► restore severities ─► de-duplicate ─► cap
                                                          │
                                         inline comments · summary · labels

1. Classify. Each changed file is matched against the profile's file_types rules (a deterministic match on file names, no LLM). A file matching no rule is skipped. Go files that embed SQL can additionally be routed to the SQL reviewer.
2. Review. Every (file, reviewer) pair becomes an independent agent with its own context, pulled from a work queue by a pool of workers. Reviewers are read-only: they can read and search the checkout, but writes are refused and there is no shell.
3. Filter. Findings that don't land on a line of the diff are dropped. A ranking agent purges compile-time claims (the code already builds), style nits and unsupported opinions, then selects findings up to a budget. Duplicates of anything already on the MR are removed.
4. Post, with retries, a fallback to a general note when a line can't be anchored, and a refusal to post any comment with no text in it.

Eleven reviewers ship built in: service_reviewer (technical quality), service_business_reviewer (does the code do what the ticket asked), sql_reviewer, test_reviewer, e2e_reviewer (browser end-to-end specs), typescript_reviewer, html_reviewer, scss_reviewer, dataview_reviewer, pbook_reviewer (message catalogues) and rules_reviewer (the .aid house rules the other reviewers read).

Quickstart

You need a GitLab personal access token with api scope, and a key for any OpenAI-compatible LLM endpoint (OpenRouter works out of the box).

git clone https://github.com/systemgroup/codereviewagent.git
cd codereviewagent
cp .env.example .env        # set DEFAULT_LLM_API_KEY, DEFAULT_LLM_MODEL, GITLAB_URL, GITLAB_TOKEN

docker build -t codereviewagent reviewer
docker run --rm --env-file .env codereviewagent \
  python main.py --gitlab-mr "https://gitlab.example.com/group/project/-/merge_requests/42"

Run it on every merge request (GitLab CI)

Add a job to the project you want reviewed:

ai-review:
  stage: test
  image: ghcr.io/systemgroup/codereviewagent:latest   # or your own build
  variables:
    GIT_STRATEGY: none          # the reviewer makes its own checkout
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - cd /app && python main.py --gitlab-mr "$CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID"

Put DEFAULT_LLM_API_KEY, DEFAULT_LLM_MODEL, GITLAB_URL and GITLAB_TOKEN in Settings → CI/CD → Variables (masked). The token needs api scope, which also covers the read-only clone.

Run the whole stack locally

docker compose up -d      # reviewer web UI on :5000, analytics collector on :8000, PostgreSQL

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗