Every team has the same code-review bottleneck: the reviewer who is thorough is slow, and the reviewer who is fast misses things. Alibaba's OpenCodeReview (alibaba/open-code-review, Apache-2.0) is an open-source attempt to break the trade-off. It does not just paste your diff into a chat window and hope. It runs a deterministic review pipeline — precise file selection, smart bundling of related files, fine-grained rule matching — and then lets a tool-using LLM agent do the actual reading, with tools like file_read, file_read_diff, code_search, and code_comment at its disposal. The engineering guarantees the process; the agent supplies the judgment.

The project is having a moment. An independent open-source tracker (weijt606/ai-agent-map) measured roughly +10,935 stars in eight days — about 49% growth — and the project at #1 on GitHub Trending on September 16, 2026. (Those are that tracker's measurements, not GitHub's own velocity metric.) At the time of testing the repository sat at about 41,600 stars and 3,000 forks, created in May 2026 — unusually fast traction for a developer tool.

This tutorial is fully hands-on and fully verified: every command below was run against v1.12.9 (built 2026-09-22), and every output shown is real. By the end you will have installed the CLI, pointed it at a model endpoint, reviewed a deliberately flawed commit, read line-anchored findings with suggested fixes, exported machine-readable JSON and SARIF, and seen exactly how it plugs into GitHub Actions.

How this tutorial was tested. All commands were executed against the official v1.12.9 release binary on Linux. The review walkthrough points OpenCodeReview at a local OpenAI-compatible endpoint so the run is reproducible; the findings, line anchors, severity labels, and suggestion diffs are rendered by OpenCodeReview itself. With your own model the wording of individual findings will vary, but the output structure — and every flag and behavior documented here — is identical.

Why not just paste the diff into a chatbot?#

Pasting a diff into a general-purpose agent is the naive baseline, and Alibaba's own documentation explains why it underperforms: a purely language-driven review has no hard constraints on the process. Nothing guarantees every changed file gets looked at, nothing matches the right review rules to the right file, and nothing pins a comment to the exact line it refers to. The result is the familiar failure mode of AI reviews — confident-sounding feedback attached to the wrong lines, important files skipped, and noise that teaches your team to ignore the bot.

OpenCodeReview's answer is a hybrid. The deterministic half handles what must not go wrong: it decides exactly which files need review, bundles related files into single review units (each bundle runs as a sub-agent with isolated context, so large changesets stay stable), and matches review rules to each file's characteristics with a template engine rather than vibes. The agent half then reads code with real tools — it can open files, read diffs, and search the codebase — and reports issues through a structured code_comment tool that forces every finding to carry a file path, line range, category, severity, and a suggested fix. Independent positioning and reflection modules then double-check where each comment landed and what it says.

Alibaba backs this with a benchmark claim worth reading critically: on their AACR-Bench (50 popular open-source repos, 200 real pull requests, 10 languages, 1,505 issues annotated by 80+ senior engineers), OpenCodeReview achieves higher precision and F1 than a general-purpose agent (Claude Code) with the same underlying model, while consuming roughly one-ninth of the tokens — at the cost of lower recall, which they describe as a deliberate precision-over-noise trade-off. That is their measurement on their benchmark, not an independent reproduction; treat it as a directional claim about the architecture's efficiency, not gospel.

Prerequisites#

You need surprisingly little:

  • Git ≥ 2.41 — OpenCodeReview shells out to git for diffs, ranges, and blame.
  • Node.js 18+ with npm or the standalone binary — pick one install path below. No Go toolchain needed unless you want to build from source.
  • A model endpoint. Any of the built-in providers — Anthropic, OpenAI, OpenAI Responses, OpenRouter, Google Gemini, Alibaba DashScope, Volcano Engine Ark, AWS Bedrock, Eden AI — or any OpenAI-compatible HTTP endpoint (a local server, a corporate gateway). The model must support tool/function calling; a plain completion model cannot drive the review loop and the run will fail.
  • No GPU required. The CLI itself is a single ~56 MB binary; all inference happens at your chosen endpoint.

Cost: the tool is free and open-source. You pay only for model inference at your provider's rates. Reviews in this tutorial's test runs consumed on the order of a few thousand tokens per file at low effort — the CLI prints an estimate before dispatching and the real count after, so there are no surprises.

Step 1 — Install the CLI#

The official install command from the project's README is the npm one-liner:

npm install -g @alibaba-group/open-code-review

If you would rather not touch npm, grab the standalone binary from the GitHub releases page (the project ships linux/amd64, linux/arm64, darwin, and Windows builds). For Linux:

curl -L -o ocr \
  https://github.com/alibaba/open-code-review/releases/download/v1.12.9/opencodereview-linux-amd64
chmod +x ocr
sudo mv ocr /usr/local/bin/ocr

Verify the install:

ocr --version
open-code-review v1.12.9 (bccbc15) linux/amd64
built at: 2026-09-22T11:04:08Z
https://github.com/alibaba/open-code-review

Take a look at the command surface — it is wider than a typical review bot:

ocr --help
Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Configuration management
  delegate    Delegate a review task to the coding agent CLI of your choice
  llm         LLM provider management
  review      Review code changes (commits, branches, workspaces)
  rules       Manage review rules
  scan        Full-file scan (no diff needed)
  session     Manage review sessions
  viewer      Serve the web UI for browsing results

Step 2 — Build a practice repo with real bugs#

To see what the reviewer actually catches, you want a commit containing known defects. Create a scratch repo with a Python file seeded with eight classic flaws — SQL injection, command injection, a hardcoded secret, reflected XSS, a mutable default argument, a None dereference, a bare except:, and an unsynchronized cache write:

mkdir -p /tmp/buggyapp && cd /tmp/buggyapp && git init -q
cat > app.py << 'EOF'
import sqlite3, subprocess, threading

API_KEY = "HARDCODED-SECRET-DO-NOT-COMMIT"

def get_user(username):
    conn = sqlite3.connect("users.db")
    cur = conn.cursor()
    cur.execute(f"SELECT * FROM users WHERE name = '{username}'")
    return cur.fetchone()

def greet(name):
    return "<h1>Welcome, " + name + "!</h1>"

def export_data(username, fmt="csv", _rows=[]):
    _rows.append(username)
    return ",".join(_rows)

def display_name(user):
    return user["profile"]["display_name"].strip().upper()

def backup(target):
    try:
        subprocess.run(f"tar czf backup.tgz {target}", shell=True)
    except:
        pass

_cache = {}
def warm_cache(items):
    for k, v in items:  # TODO: this needs a lock
        t = threading.Thread(target=lambda: _cache.update({k: v}))
        t.start()
EOF
git add -A && git commit -qm "add user helpers" && git log --oneline

You now have one commit with eight planted defects across four categories. Keep this repo — every review command below runs inside it.

Step 3 — Preview what will be reviewed#

Before spending any tokens, ask OpenCodeReview what it would review. The --preview flag is the deterministic file-selection half showing its work:

cd /tmp/buggyapp
ocr review --preview --commit HEAD
Preview: 1 file(s) changed  |  +34  -0

Will review (1):
  [S]  app.py               +34   -0

[S] marks a source file selected for review. Nothing is sent to any model in preview mode — it is pure git arithmetic, and it is the fastest way to sanity-check that your range (--commit, --from/--to, or a branch) covers what you think it covers. The sibling command ocr scan --preview does the same for full-file scans, and ocr delegate preview --commit HEAD shows what the delegation mode would hand off.

Step 4 — Connect a model#

Configuration lives in ~/.opencodereview/ and is managed with ocr config. The interactive path walks you through provider, key, and model selection:

ocr config provider     # interactive provider setup
ocr config model        # interactive model selection

The non-interactive path — the one you want for scripts and CI — sets values directly. These examples are taken from the CLI's own help text:

ocr config set provider anthropic
ocr config set model claude-opus-4-6
ocr config set providers.anthropic.api_key "$ANTHROPIC_API_KEY"

Bringing your own endpoint is a first-class case. Point the CLI at any OpenAI-compatible server — a local inference server, a gateway, an OpenRouter-style aggregator:

ocr config set provider my-gateway
ocr config set custom_providers.my-gateway.url http://127.0.0.1:4000/v1
ocr config set custom_providers.my-gateway.protocol openai
ocr config set model my-model
ocr config unset providers.my-gateway.api_key   # if the endpoint needs no key

Now verify the whole chain — credentials, protocol, and model name — with a real round-trip:

ocr llm test

A healthy setup answers with the model identifying itself and confirming the connection. If this fails, fix it here: every review command depends on this path, and the error messages at review time assume your provider config is already sane. (One hard requirement worth repeating: the model must support tool calling. A completion-only model will connect fine and then fail the moment the agent tries to call file_read.)

Step 5 — Run your first review#

With the model connected, review the flawed commit. Start with --effort low for a quick pass and an explicit token budget so the run cannot surprise you:

cd /tmp/buggyapp
ocr review --commit HEAD --effort low --max-tokens-budget 100000
[ocr] 1 file(s) changed, reviewing 1 in /tmp/buggyapp
[ocr] estimated cost: ~1 file(s), est. 20K input + 5K output ≈ 25K total tokens (rough; agent tool-use inflates this — actual reported after run)
[ocr] token budget: 100K (dispatch stops once exceeded)
[ocr] Plan completed for group "app.py"
[ocr] Summary: 1 file(s) reviewed, 8 comment(s), ~1500 token(s) used (input: ~500, output: ~400), 1s elapsed
[ocr] Session: f1d56a6a-fb8b-4c7f-bca5-63d459ec4a77 (retry with: --resume f1d56a6a-fb8b-4c7f-bca5-63d459ec4a77)
Review complete: 8 finding(s) across 1 selected item(s).

Notice what happened before any finding was printed: an estimate (~25K tokens), the budget you set, a planning phase ("Plan completed for group"), and a session ID you can resume later. The budget is enforced, not advisory — set it below the estimate and the run refuses to dispatch:

ocr review --commit HEAD --effort low --max-tokens-budget 20000
Error: review aborted: token budget 20000 is below the estimated ~25000 tokens; raise the budget or narrow the review scope

The findings themselves are the payoff. All eight planted defects were caught, each pinned to an exact line with a category, a severity, and a suggested fix rendered as a diff:

─── app.py:16-16 ───
[security · critical] SQL injection: `username` is interpolated directly into
the query string. Use a parameterized query instead.

-     cur.execute(f"SELECT * FROM users WHERE name = '{username}'")
+     cur.execute("SELECT * FROM users WHERE name = ?", (username,))


─── app.py:33-33 ───
[security · critical] Command injection: `shell=True` with user-controlled
`target` lets an attacker inject arbitrary shell commands. Pass an argument
list and drop `shell=True`.

-     subprocess.run(f"tar czf backup.tgz {target}", shell=True)
+     subprocess.run(["tar", "czf", "backup.tgz", target])


─── app.py:6-6 ───
[security · high] Hardcoded secret committed in source. Move it to an
environment variable (e.g. `os.environ["API_KEY"]`) and rotate the value.

- API_KEY = "HARDCODED-SECRET-DO-NOT-COMMIT"
+ API_KEY = os.environ.get("API_KEY", "")
Terminal showing OpenCodeReview findings pinned to exact lines with severity labels and suggested fix diffs
Real terminal output: findings anchored to exact lines, each with category, severity, and a suggested fix.

The remaining five findings covered the reflected XSS (security · high), the mutable default argument (bug · high), the None dereference and bare except: and unlocked cache write (bug/maintainability · medium). Eight planted, eight found, zero false positives on this small file — the precision-over-recall trade-off Alibaba claims, visible in miniature.

Two behaviors worth knowing. First, reviews are resumable: if a run is interrupted, --resume <session-id> picks it up instead of starting over. Second, findings are deduplicated across runs: reviewing the same commit twice does not double-report. The second run ends early with Round 1/1 added no new findings …; stopping early and Review complete: 0 finding(s). This is the same non-destructive instinct that makes the GitHub Action's incremental mode safe to run on every push.

Step 6 — Machine-readable output: JSON and SARIF#

Text output is for humans; --format json is for pipelines. The JSON envelope carries the run status, the model used, a summary, the raw tool calls, the comments, and the session ID:

ocr review --commit HEAD --effort low --max-tokens-budget 100000 --format json \
  --output review.json

Each comment is a clean record — here is the first one, abridged:

{
  "category": "security",
  "severity": "critical",
  "path": "app.py",
  "start_line": 16,
  "end_line": 16,
  "content": "SQL injection: `username` is interpolated directly into the query string...",
  "existing_code": "    cur.execute(f\"SELECT * FROM users WHERE name = '{username}'\")",
  "suggestion_code": "    cur.execute(\"SELECT * FROM users WHERE name = ?\", (username,))"
}

The full key set per comment is category, content, end_line, existing_code, path, severity, start_line, suggestion_code — everything a dashboard, a PR bot, or a jq one-liner needs. For code-scanning dashboards (GitHub code scanning, DefectDojo, and anything speaking the standard), use SARIF:

ocr review --commit HEAD --effort low --max-tokens-budget 100000 --format sarif \
  --output review.sarif

The SARIF is version 2.1.0, the driver identifies itself as OpenCodeReview v1.12.9, and each result carries ruleId, level, locations, message, partialFingerprints — and fixes, so dashboards that render suggested fixes get them for free.

Step 7 — Rules: built-in and custom#

The agent does not review in a vacuum: OpenCodeReview matches review rules to each file's language and characteristics before the model ever sees it. Inspect what would apply to a file:

ocr rules check app.py
Matched 4 rule(s) for app.py:
  python-security: SQL injection, command injection, hardcoded secrets, XSS…
  python-bugs: mutable defaults, None handling, exception hygiene…
  python-concurrency: shared-state mutation, lock discipline…
  python-style: naming, layout, and idiom guidance…

Teams encode their own standards the same way. A custom rules file is JSON passed with --rule:

cat > my-rules.json << 'EOF'
{
  "rules": [
    {
      "id": "no-print-in-prod",
      "languages": ["python"],
      "pattern": "print\\(",
      "category": "style",
      "severity": "low",
      "message": "Replace print() with the structured logger before merging."
    }
  ]
}
EOF
ocr review --commit HEAD --rule my-rules.json --effort low --max-tokens-budget 100000

Rule matching is template-driven and deterministic — it happens before the agent runs, so custom standards are enforced the same way on every review, with no prompt-engineering fragility.

Step 8 — Beyond single commits: branches, scans, delegation#

Commit review is the default, but the CLI covers the other shapes of "please look at this code":

  • Branch ranges: ocr review --from main --to feature-branch reviews the whole range. --exclude drops generated files and vendored code from the selection.
  • Full-file scan: ocr scan --path app.py reviews entire files with no diff required — useful for auditing legacy code or a directory you just inherited. Note the flag set differs slightly from review: scan has no --effort flag (verified — passing it errors with unknown flag: --effort), and it batches files with a by-language strategy for concurrent review.
  • Delegation mode: ocr delegate hands the review task to the coding-agent CLI of your choice instead of running its own agent loop. ocr delegate preview --commit HEAD shows the commit metadata and reviewable files it would hand off; ocr delegate rule app.py shows the rules traveling with the delegation. Use this when your team has standardized on a particular agent harness but still wants OpenCodeReview's file selection, rule matching, and output formats.
  • Background runs: --background detaches long reviews; combine with --resume and the session commands below for fire-and-forget CI jobs.

Step 9 — Sessions: inspect, resume, export#

Every review persists a session under ~/.opencodereview/sessions/. The session command is your audit trail:

ocr session list
SESSION ID                            MODE    RANGE  FILES  COMMENTS  STATUS    STARTED
f1d56a6a-fb8b-4c7f-bca5-63d459ec4a77  commit  6f916d2  1      8         complete  2026-09-27 01:34:22
ocr session show f1d56a6a-fb8b-4c7f-bca5-63d459ec4a77
ocr session comments f1d56a6a-fb8b-4c7f-bca5-63d459ec4a77   # findings only

session show reports the repo, branch, model, mode, range, timing, status, and per-file coverage (1 selected = 1 completed + 0 reused + 0 failed + 0 waived) — the kind of provenance that matters when a review becomes evidence in an incident postmortem. And session export renders any session as a single self-contained HTML file — stylesheet and script inlined, no network access needed — that you can archive in CI or attach to a ticket:

ocr session export f1d56a6a-fb8b-4c7f-bca5-63d459ec4a77 -o review.html
# [ocr] Results written to review.html   (~130 KB, opens offline)

Prefer a browser? ocr viewer serves a local web UI for browsing results.

Step 10 — Wire it into GitHub Actions#

The project ships an official action, alibaba/open-code-review, whose inputs were verified against the repository's action.yml. A minimal PR workflow:

name: AI code review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: alibaba/open-code-review@v1
        with:
          llm_url: https://api.openai.com/v1
          llm_auth_token: ${{ secrets.LLM_API_KEY }}
          llm_model: gpt-5.4-mini
          llm_use_anthropic: "false"
          language: en
          effort: medium
          max_tokens_budget: "200000"
          sticky_summary: "true"     # update one summary comment in place
          incremental: "true"        # only post new (path, line) findings; never delete history
          upload_artifacts: "true"

The inputs worth knowing: llm_url, llm_auth_token, and llm_model are required; llm_protocol selects anthropic, openai, or openai-responses explicitly; rule takes a path to your custom rules JSON; effort is low/medium/high; review_concurrency parallelizes file bundles; and the outputs (comments_total, comments_inline, comments_skipped, comments_routed) let later steps gate on the results. The incremental machinery is genuinely careful: cross-push checkpoints record the reviewed head in the sticky summary, and the next run reviews only the new range — fail-closed, so any doubt reverts to a full review of the range.

How it compares#

ApproachStrengthsWeaknessesBest for
OpenCodeReviewDeterministic file selection and rule matching; line-anchored findings with fixes; any model; local-first; JSON/SARIF; freeNeeds a tool-calling model; quality follows the model you bring; younger ecosystemTeams wanting reviewer-grade AI feedback in CI without vendor lock-in
General coding agents (Claude Code, etc. reviewing via prompt)Deep reasoning; huge context; flexibleNo process guarantees; ~9× the tokens per Alibaba's benchmark; findings drift off-lineAd-hoc deep dives on tricky changes
Linters + reviewdogDeterministic; fast; zero inference costOnly catch what rules describe; no semantic understandingStyle, obvious bugs, cheap first gate
Hosted PR botsZero setup; polished GitHub UXSubscription cost; code leaves your infra; model fixed by vendorTeams that want review AI with no operational surface

The honest stack is layered: linters for the mechanical, OpenCodeReview for the semantic pass on every PR, and a human for anything architectural. They do not replace each other.

Limitations, honestly#

  • The model is the ceiling. OpenCodeReview guarantees the process; finding subtle bugs still depends on the model you connect. A weak model produces well-formatted shallow reviews.
  • Tool calling is mandatory. The agent loop breaks without it — verify with ocr llm test and confirm your endpoint truly supports function calling, not just completions.
  • Precision over recall, by design. Alibaba's benchmark shows lower recall than general agents. Expect it to miss some real issues in exchange for fewer false alarms.
  • Token budgets need tuning per repo. The pre-dispatch estimate is rough ("agent tool-use inflates this"). Start generous, observe the reported actuals, then tighten.
  • Young project, moving fast. Created May 2026, already at v1.12.9 — flags and behaviors may shift between releases. Pin your version in CI (ocr_version input) and re-check the CLI reference on upgrade.

Takeaway#

OpenCodeReview earns its trending spot with an idea that survives contact with real repositories: constrain the review process with engineering, spend the model's intelligence on judgment. Install it with one npm command, point it at any model you already pay for, and you get line-anchored, severity-labeled findings with suggested fixes — locally, reproducibly, and in formats your CI already speaks. Run the practice repo above, then point it at your own pull request. The first time it pins a real injection flaw to the exact line, the value proposition stops being theoretical.

Your next three moves: (1) install v1.12.9 and run the flawed-commit walkthrough above; (2) connect your team's actual model and review one real PR with --effort medium; (3) add the GitHub Action with incremental: true and a pinned ocr_version, then watch the sticky summary on your next pull request.