Tired of Unreliable AI Code Reviews? Try This Open Source Tool from Alibaba
Have you ever found that during team code reviews, some basic mistakes keep slipping through? Or when you ask a general-purpose AI coding assistant to review your code, it either skips half the files, reports issues with wrong line numbers, or gives inconsistent results every time?
If you’ve used tools like Claude Code for code review, you’ve probably run into these problems. When the changeset is large, the AI tends to take shortcuts and only looks at a subset of files. The line numbers in its comments often don’t match the actual code. And the review quality can feel like a lottery – unpredictable from one run to the next.
To solve these problems, Alibaba has open sourced its internal AI code review assistant. For two years, it served tens of thousands of developers inside the company and caught millions of defects. Now it’s available to everyone. It’s called 「Open Code Review」 (OCR for short).
OCR is not a general chatbot. It’s a command-line tool (CLI) designed specifically for code review. You just configure a model endpoint, point it at your Git repository, and it produces structured, line‑level review comments.
Why General AI Assistants Struggle with Code Review
Before we dive into OCR, let’s quickly understand why general AI assistants often fail at code review.
You’ve probably seen three typical issues:
-
「Incomplete coverage」 – When your changes are large, the AI tends to be lazy and reviews only part of the files. For example, a feature change touches 20 files, but the AI carefully looks at only 10 and glances over the rest. Those skipped files might hide serious defects.
-
「Position drift」 – The reported file names or line numbers often don’t match the actual code. The AI says “null pointer risk at line 35”, but line 35 is either empty or completely unrelated. This happens because language models struggle to understand diff formats and original file positions accurately.
-
「Unstable results」 – AI behavior driven by natural language prompts can change dramatically with small wording changes. Modify a few words in the prompt, and the depth, strictness, or even the output format may shift. You can’t rely on it to be consistent.
The root cause is simple: a purely language‑driven architecture lacks 「strong constraints」 on the review process. The AI decides which files to look at and how to locate line numbers, with no enforced rules. Open Code Review solves this with a hybrid design: 「deterministic engineering + Agent」.
Core Design: Who Does What?
The idea is clean: put the things that must never fail under deterministic engineering logic, and let the Agent handle dynamic decisions and context retrieval – where AI truly shines.
Deterministic Engineering – Strong Constraints
These parts are handled by code logic, not by a language model. This prevents “laziness” and “drift” from the start.
-
「Precise file filtering」 – Rules decide exactly which files to review (e.g., src/main/**/*.java) and which to skip (e.g.,**/generated/**). Important changes are never missed. -
「Smart file bundling」 – Related files are grouped into a single review unit. For instance, message_en.propertiesandmessage_zh.propertiesare bundled together. Each bundle goes to a separate sub‑agent with its own context – a divide‑and‑conquer strategy that handles huge changesets reliably and supports concurrent reviews. -
「Fine‑grained rule matching」 – Different file types (Java files, XML configs, SQL mappers) automatically match the appropriate review rules. Compared to describing rules in natural language prompts, this template‑based approach is much more stable and predictable. It also helps the model focus on the most relevant aspects of each file. -
「External location and reflection components」 – Independent modules for comment positioning and content reflection systematically correct location errors and content mistakes. When the AI raises a plausible but incorrectly positioned issue, the reflection module double‑checks it, dramatically improving accuracy.
Agent – Dynamic Decision Making
Inside the framework built by deterministic engineering, the Agent can do what it does best:
-
「Scenario‑specific prompt tuning」 – Prompts are deeply optimised for code review. This improves quality while reducing token usage (and API costs). -
「Scenario‑specific toolset」 – By analysing tool‑call patterns from large amounts of real‑world data – call frequencies, repetition rates, impact of new tools on the call chain – the team trimmed and split the generic Agent toolset. The result is a dedicated toolset that is much more stable and predictable for code review. It lets the Agent efficiently read full file contents, search the codebase, and check other changed files for context – enabling deep review, not just surface‑level diff comments.
How to Install Open Code Review
Open Code Review is a command‑line tool for macOS, Linux, and Windows. Choose the method you prefer.
Install via NPM (recommended)
If you already have Node.js, this is the easiest way. Run:
npm install -g @alibaba-group/open-code-review
After installation, the ocr command is available globally.
Download the binary from GitHub Releases
You can also download the pre‑built binary for your OS.
「macOS (Apple Silicon – M1/M2/M3)」
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
「macOS (Intel)」
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
「Linux (x86_64)」
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
「Linux (ARM64)」
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
「Windows (x86_64)」
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe
Then move ocr.exe into a directory on your PATH (e.g., C:\Windows\System32).
「Windows (ARM64)」
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe
Build from source
If you prefer to build from source:
git clone https://github.com/alibaba/open-code-review.git
cd open-code-review
make build
sudo cp dist/opencodereview /usr/local/bin/ocr
Configuring an LLM
Before you can review code, you must configure an LLM endpoint. You don’t need to host a model yourself – just an API key for a provider like Anthropic (Claude), OpenAI (GPT), or local options like DashScope, DeepSeek, etc.
OCR supports several configuration methods. Choose the one you like.
Method A: Interactive setup (recommended)
This is the simplest. Run:
ocr config provider
You’ll see a list of built‑in providers (anthropic, openai, dashscope, deepseek, etc.). Pick one, or add a custom provider.
Then run:
ocr config model
This lists the available models for your chosen provider. Select one, and the API URL and model name will be filled in automatically.
Method B: Manual configuration
If you prefer to do it yourself, use ocr config set:
ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token your-api-key-here
ocr config set llm.model claude-opus-4-6
ocr config set llm.use_anthropic true
The configuration is stored at ~/.opencodereview/config.json.
「About auth_header」 – For Anthropic’s API, if you’re using a standard sk-ant-* API key, you need to set the auth header to x-api-key:
ocr config set llm.auth_header x-api-key
For other OpenAI‑compatible endpoints, the default authorization (Bearer token) works.
Method C: Environment variables (highest priority)
Environment variables override the config file.
export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=your-api-key-here
export OCR_LLM_MODEL=claude-opus-4-6
export OCR_USE_ANTHROPIC=true
OCR also respects Claude Code’s environment variables (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL). If you already use Claude Code, this may be convenient.
Test the connection
After configuration, test that everything works:
ocr llm test
If the setup is correct, you’ll see a success message.
Your First Code Review
Assume you’re inside a Git repository (e.g., after cd your-project) and you’ve configured an LLM. Now run your first review.
OCR supports three common scenarios.
Workspace mode – review all uncommitted changes
This is the most common mode. It reviews all staged, unstaged, and untracked changes in your working directory.
ocr review
OCR will analyse the changed files, call the LLM, and output line‑level comments to the terminal.
Branch range mode – compare two refs
To review all differences from main to feature-branch:
ocr review --from main --to feature-branch
This is very useful in CI/CD pipelines – for example, automatically reviewing changes when a merge request is created.
Single commit mode – review one commit
To review a specific commit:
ocr review --commit abc123
Here abc123 is the commit hash (can be a short hash).
Other useful parameters
| Parameter | Short flag | Default | Description |
|---|---|---|---|
--preview |
-p |
false |
Only list files that would be reviewed, without calling the LLM |
--format |
-f |
text |
Output format: text (human‑readable) or json (machine‑readable) |
--concurrency |
— | 8 |
Maximum concurrent file reviews |
--timeout |
— | 10 |
Timeout per concurrent task (minutes) |
--audience |
— | human |
human shows progress, agent prints a concise summary |
--background |
-b |
— | Provide business context (e.g., “Add rate limiting to login API”) |
--rule |
— | — | Path to a custom JSON rules file |
--max-tools |
— | built‑in default | Maximum tool‑call rounds per file (only if greater than template default) |
「Example」 – JSON output with higher concurrency:
ocr review --from main --to my-feature --concurrency 4 --format json
「Example」 – Provide background context:
ocr review --background "Add rate limiting to login API"
Integrating with Your AI Coding Assistant
If you use Claude Code, Codex, or another AI coding assistant, you can add OCR as a slash command or skill. Then your assistant can call OCR whenever a review is needed.
Option 1: Install as a Skill (for assistants that support Skills)
Use npx to install the OCR skill into your project:
npx skills add alibaba/open-code-review --skill open-code-review
This installs the open-code-review skill from the skills registry. It teaches your coding assistant how to run ocr, classify issues by priority, and optionally apply fixes.
Option 2: Install as a Claude Code plugin
If you use Claude Code, run:
/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review
After installation, use /open-code-review:review to trigger OCR reviews. The plugin can also automatically filter and fix some issues.
Option 3: Install as a Codex plugin
For local Codex, add this repository as a plugin marketplace:
codex plugin marketplace add alibaba/open-code-review
codex
/plugins
After installing and enabling the Open Code Review plugin, start a new Codex thread and invoke it like:
@Open Code Review review my current changes
@Open Code Review review this branch against main
@Open Code Review review and fix high-confidence issues
Option 4: Copy the command file directly (no package manager)
If you don’t want to use any package manager, download the command file directly into Claude Code’s configuration directory.
「Project‑level」 (share with your team via git):
mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
「User‑level」 (personal, works for all projects):
mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
❝
「Note」: All integration methods require that you have already installed and configured the
ocrCLI on your system.❞
Using OCR in CI/CD (GitHub Actions / GitLab CI)
You can run Open Code Review automatically when a merge request or pull request is created. This is a great way to enforce code quality.
The core command for CI is:
ocr review \
--from "origin/main" \
--to "origin/feature-branch" \
--format json
The --format json flag makes OCR output structured JSON, easy to parse in CI scripts.
For concrete examples, see the examples/ directory:
-
github_actions/– GitHub Actions integration -
gitlab_ci/– GitLab CI integration
Command Quick Reference
| Command | Alias | Description |
|---|---|---|
ocr review |
ocr r |
Start a code review |
ocr rules check <file> |
— | Preview which rules would apply to a given file path |
ocr config provider |
— | Interactive provider setup (built‑in, custom, or manual) |
ocr config model |
— | Interactive model selection for the current provider |
ocr config set <key> <value> |
— | Set a configuration value |
ocr llm test |
— | Test LLM connectivity |
ocr llm providers |
— | List built‑in LLM providers |
ocr viewer |
ocr v |
Start WebUI session viewer at localhost:5483 |
ocr version |
— | Show version information |
Review Rules: How to Customise What the AI Checks
Open Code Review lets you define review rules in JSON files. The rule system has four priority layers. The first match wins.
| Priority | Source | Path | Description |
|---|---|---|---|
| 1 (highest) | --rule parameter |
User‑supplied path | Temporary override for one‑off reviews |
| 2 | Project config | <repoDir>/.opencodereview/rule.json |
Team‑shared, can be committed to git |
| 3 | Global config | ~/.opencodereview/rule.json |
Personal preferences for all projects |
| 4 (lowest) | System default | Embedded system_rules.json |
Built‑in rules for common languages and file types |
Rule file format
A rule file is a JSON object with a rules array. Each rule has a path (file matching pattern) and a rule (the specific review instruction).
{
"rules": [
{
"path": "force-api/**/*.java",
"rule": "All new methods must validate required parameters for null"
},
{
"path": "**/*mapper*.xml",
"rule": "Check for SQL injection risks, wrong parameters, and missing closing tags"
}
]
}
-
pathsupports**recursive matching and brace expansion like{java,kt}. -
Within each layer, rules are evaluated in declaration order – the first match wins. -
If a rule file does not exist, it is silently skipped.
Path filtering: which files get reviewed?
Besides the rules array, a rule file can also have include and exclude fields to control the scope.
{
"rules": [
{"path": "**/*.java", "rule": "Check null safety"}
],
"include": ["src/main/**/*.java", "lib/**/*.kt"],
"exclude": ["**/generated/**", "vendor/**"]
}
The filtering decision priority (highest to lowest):
| Step | Condition | Result |
|---|---|---|
| 1 | File is binary | Exclude |
| 2 | Path matches user exclude pattern |
Exclude |
| 3 | File extension not in supported list | Exclude |
| 4 | include is configured and path matches |
「Include」 (skip step 5) |
| 5 | Path matches built‑in default exclude patterns (test files, etc.) | Exclude |
| 6 | None of the above | Include |
「Important points」:
-
includeandexcludefollow the same priority chain as review rules (--rule> project config > global config). The layer that hasinclude/excludeat the highest priority is used in full – they are not merged across layers. -
excludealways wins overinclude. A file matching both is excluded. -
includeis meant to 「override the built‑in default exclude patterns」 (like test files), not to restrict the review scope. Files that do not matchincludestill go through the normal default filtering steps.
「Built‑in default exclude patterns」 (used to filter out test files; can be overridden via include):
**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs,
**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**,
**/src/test/java/**/*.java, **/src/test/**/*.kt,
**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py,
**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/**
Full Configuration Reference
The global configuration file is ~/.opencodereview/config.json. You can edit it manually.
| Key | Type | Example |
|---|---|---|
provider |
string | anthropic | openai | dashscope | deepseek | z-ai |
providers.<name>.api_key |
string | Provider API key |
providers.<name>.url |
string | Base URL override |
providers.<name>.protocol |
string | anthropic | openai |
providers.<name>.model |
string | Model name for that provider |
providers.<name>.auth_header |
string | x-api-key | authorization |
custom_providers.<name>.* |
— | Same fields as providers.<name>.* |
llm.url |
string | https://api.openai.com/v1/chat/completions |
llm.auth_token |
string | sk-xxxxxxx |
llm.auth_header |
string | For Anthropic: x-api-key | authorization |
llm.model |
string | claude-opus-4-6 |
llm.use_anthropic |
boolean | true | false |
language |
string | English | Chinese (default: Chinese) |
telemetry.enabled |
boolean | true | false |
telemetry.exporter |
string | console | otlp |
telemetry.otlp_endpoint |
string | OTLP collector address |
telemetry.content_logging |
boolean | Include prompts in telemetry (use with care) |
Environment variables take precedence over the config file.
Environment variables
| Variable | Purpose |
|---|---|
OCR_LLM_URL |
LLM API endpoint URL |
OCR_LLM_TOKEN |
API key / auth token |
OCR_LLM_AUTH_HEADER |
Anthropic auth header (x-api-key or authorization) |
OCR_LLM_MODEL |
Model name |
OCR_USE_ANTHROPIC |
true = Anthropic protocol, false = OpenAI protocol |
Telemetry: Monitoring How OCR Runs
Open Code Review includes OpenTelemetry integration for collecting spans and metrics. This is turned off by default.
To enable it:
ocr config set telemetry.enabled true
ocr config set telemetry.exporter otlp # or console
ocr config set telemetry.otlp_endpoint localhost:4317
If you set telemetry.content_logging to true, prompts and responses will be included in telemetry data (be aware of privacy).
Frequently Asked Questions (FAQ)
「Which programming languages does Open Code Review support?」
There is no hard limit – it works with any text file. The built‑in default rules cover Java, Go, Rust, Python, Ruby, JavaScript/TypeScript, as well as XML, SQL, and properties files. You can extend support for other languages with custom rules.
「Do I have to use Anthropic’s Claude models?」
No. OCR supports multiple built‑in providers (OpenAI, DashScope, DeepSeek, Z‑AI, etc.) and also any custom endpoint that is compatible with the OpenAI or Anthropic protocol. You only need a valid API key.
「How many tokens does a typical review consume?」
It depends on the size and number of changed files. OCR’s scenario‑specific prompt tuning and divide‑and‑conquer strategy already reduce token usage significantly. A medium‑sized change (say 10–20 files) might consume a few thousand to tens of thousands of tokens. Use --preview to see the list of files that will be reviewed and estimate the cost.
「Can I make OCR review only specific files?」
Yes. Use the include and exclude fields in a rule file to precisely control the scope. Alternatively, you can use Git’s staging area: git add only the files you want, then run ocr review (workspace mode includes both staged and unstaged changes). If you want to review only staged changes, you can currently script it with git diff --cached, but OCR does not have a dedicated parameter for that.
「What if the AI still reports issues with wrong positions?」
First, OCR’s built‑in location and reflection modules have already greatly reduced position drift. If you still see it, check whether the code files were modified after the review started but before it finished. You can also try increasing the tool‑call rounds per file with --max-tools to let the AI double‑check positions more thoroughly. In rule files, you can add stricter positioning requirements for specific file types.
「How can my team share review rules?」
Simply put the rule file at .opencodereview/rule.json in your project root and commit it to git. When team members run ocr review, the project‑level rules are loaded automatically. Note that the --rule parameter has the highest priority – if someone uses that, it overrides the project rules.
「How does Open Code Review compare to static analysis tools like SonarQube or CodeClimate?」
They are complementary. Static analysis tools use fixed rule sets (coding standards, complexity checks) for deterministic scanning – fast and complete, but they cannot understand business logic or context. OCR, using an LLM, can understand intent, detect logic errors, and suggest architectural improvements, but it is slower and more expensive. Use OCR as a layer above static analysis to catch deeper issues that rules cannot express.
「Can OCR automatically fix the issues it finds?」
The current version focuses on reviewing and reporting, not modifying code. However, when integrated with Claude Code or Codex (for example via the Skill method), the coding assistant can read OCR’s JSON output and attempt to generate fix patches. If you want fully automated fixes, you can write a script that parses --format json output and calls another tool or LLM to apply fixes.
Summary
Open Code Review is an AI‑powered code review tool that emerged from large‑scale internal use at Alibaba. Its hybrid design of 「deterministic engineering + Agent」 solves the common problems of incomplete coverage, position drift, and unstable results that plague general‑purpose AI assistants.
Whether you are a solo developer or part of a large team, you can get started quickly: install the CLI, configure an LLM endpoint, and run ocr review. It supports workspace mode, branch comparison, single commits, and can be integrated with Claude Code, Codex, GitHub Actions, GitLab CI, and more.
The rule system is flexible and powerful, allowing you to define project‑level, global, or temporary review rules, and to finely control which files are included. This is especially valuable for teams that want to enforce consistent coding standards and share best practices.
If you’re looking for a more reliable and controllable AI code review solution, give Open Code Review a try.
「Project repository」: https://github.com/alibaba/open-code-review
「License」: Apache‑2.0
