Onboarding · Open Code Review (OCR)

Overview

↩ architecture.html · generated 2026-08-14

Overview — Open Code Review (OCR)

What it is

Open Code Review (OCR), CLI command ocr, is an AI-powered code review tool written in Go. It started as Alibaba Group's internal AI code review assistant — used by tens of thousands of internal developers over roughly two years and credited with catching millions of defects — before being open-sourced (Apache-2.0) as alibaba/open-code-review.

In plain terms: ocr review reads a git diff, hands each changed file to an AI agent that can read other files and search the codebase before commenting, and produces line-precise review comments. ocr scan does the same thing for whole files (no diff needed) — useful for auditing a codebase you didn't write. ocr delegate skips OCR's own AI call entirely and instead prepares file selection + rule text for your own coding agent (Claude Code, Codex, Cursor) to review with.

Why it exists — the core design bet

The project's own README names the problem directly: general-purpose coding agents given a "review this diff" instruction tend to (1) skip files on large changesets, (2) mis-locate their own comments (wrong line/file), and (3) vary in quality between runs because a purely natural-language-driven process has no hard constraints.

OCR's answer, stated as its core philosophy, is deterministic engineering × agent hybrid: anything that must not go wrong — which files get reviewed, how they're grouped, which rule text applies, whether a comment's line number is actually correct — is plain Go code with zero model calls. The model is used only for the one thing it's actually needed for: reading code and judging whether something is a defect. See docs/design/HLD.md §"4 questions per module" and architecture.html §7 for exactly where that line falls in every package.

Three review modes

Mode Command Unit of work Calls an OCR-configured LLM?
Diff review ocr review one changed file's unified diff Yes
Full-file scan ocr scan whole file content (batched) Yes
Delegation ocr delegate file selection + rule text No — your own coding agent does the review

Inputs / outputs

Benchmark headline

OCR's own benchmark (50 open-source repos, 200 real PRs, 10 languages, 1,505 human-annotated ground-truth issues) reports a materially higher Precision/F1 than a general-purpose agent (Claude Code) using the same underlying model, at roughly 1/9th the token cost — a deliberate precision-over-recall trade-off from the deterministic file-selection and rule-matching design above.

Where the code actually lives (this project's copy)

samples/open-code-review/ is a pinned local clone of the public repo, used as the source-of-truth for every claim in these docs and for the code-graph tooling in tool-outputs/. It is Go (module github.com/alibaba/open-code-review, Go ≥ 1.25), roughly 20k lines across thirteen internal/* packages plus cmd/opencodereview. See docs/design/HLD.md for the component map and architecture.html for the interactive, click-to-expand version of the same map.

A glossary a newcomer meets immediately

Term Meaning
Diff review vs scan Review works from a git diff; scan works from whole file content (no diff, no git history needed).
Delegation mode OCR does no LLM call itself; hands file selection + rules to the user's own coding agent.
Tool-use loop The per-file conversation loop (internal/llmloop.Runner) where the model calls tools (read file, search, comment) until it calls task_done.
Manifest The immutable, per-run coverage record (internal/session) — which files completed/reused/failed, used to power --resume.
Protocol Which wire format OCR speaks to the LLM: anthropic, openai (Chat Completions), or openai-responses.
MCP Model Context Protocol — lets external tool servers register additional tools the review agent can call, alongside the six built-in ones.
SARIF Static Analysis Results Interchange Format — the machine-readable output OCR can emit for CI annotation.

Related: docs/design/HLD.md (architecture) · docs/design/data-flow.md (data flow) · docs/tools/graph-intelligence.md (how the diagrams and graphs were built).