Deep Dive: How alibaba/open-code-review Splits Code Review Between Deterministic Code and an Agent

Companion to the hands-on tutorial: Install and use alibaba/open-code-review on Cui.Guru. The tutorial shows how to use it. This post explains why it is built this way.

alibaba/open-code-review (about 50.9k stars per the GitHub API on 2026-11-14, Apache-2.0, written in Go) is an AI code review CLI. The README says it began as Alibaba’s internal review assistant. Its thesis is that reviewing through a prompt alone has “no hard constraints on the review process”, so it moves the steps that must not go wrong out of the model and into code.

The workflow in motion

Architecture

The module is laid out under internal/: diff (parsing, line resolution), agent (selection, grouping, dispatch), reviewtask and llmloop (the per-group tool loop), tool (what the model can call), session (history and resume), config (rules, prompt templates, allowlists), mcp, scan and delegate. Entry point is cmd/opencodereview.

The core design idea

Put the “must not go wrong” decisions in code, and give the model only what needs judgement. The README lists four hard constraints: precise file selection, smart file bundling, fine-grained rule matching, and external positioning and reflection modules. Each one is visible in the source.

1. File selection is a pure function

internal/agent/selection.go documents selectFiles as the review’s “one deterministic pre-dispatch selection”:

// It is pure — no output, no mutation, no git or LLM access — so `--preview`
// and the real run consume the same answer instead of each deriving their own,
// which is what let the two drift (#782).
func (a *Agent) selectFiles(diffs []model.Diff) []fileDecision {

For each file it applies static gates (binary, built-in secret paths, user include and exclude lists, an extension allowlist), a deletion check, and a per-file diff-size ceiling measured in tokens. internal/config/allowlist/default_secret_patterns.json starts with **/.ssh/**, **/id_rsa and **/.netrc, so files matching those patterns are excluded from the selected review set. That is a path gate on what gets dispatched, not a guarantee about every tool call or about secrets inside ordinary source files.

2. Grouping is a policy, not a prompt

GroupingPlan in internal/config/template/template.go chooses between three strategies using two thresholds. At or above GroupingMinFiles, an LLM groups the files, seeing only metadata (no diff content) and answering with integer indices to save output tokens (internal/agent/grouping.go). Below it, a small total churn bundles everything into one group; otherwise each file is reviewed alone. The code comment explains why: every round of a bundled group has to cover the whole set’s churn, so “past a ceiling a single round’s attention is spread too thin”.

func (t Template) GroupingPlan(fileCount int, totalChanged int64) GroupingStrategy {
	if t.GroupingMinFiles <= 0 || fileCount >= t.GroupingMinFiles {
		return GroupingViaLLM
	}
	if t.GroupingBundleLineThreshold > 0 && totalChanged < int64(t.GroupingBundleLineThreshold) {
		return GroupingBundleAll
	}
	return GroupingPerFile
}

grouping.go also sets maxFilesPerGroup = 10.

3. Each group is an isolated sub-agent with a budget

dispatchSubtasks in internal/agent/agent.go runs groups behind a semaphore (default concurrency 8). Before acquiring a slot it estimates the group’s tokens and stops scheduling if the projected total would exceed the budget; groups already running finish. A panic in one group is recovered and recorded so the others complete. The timeout is the per-task minutes multiplied by the number of review rounds, and effort presets in template/effort.go set the maximum rounds: low 1, medium 2, high 3. Groups can stop earlier.

4. The model gets a small, tuned toolset

internal/tool/definitions.go names the tools: code_comment, file_read, file_find, file_read_diff, code_search and task_done. code_comment validates a closed vocabulary: categories bug, security, performance, maintainability, test, style, documentation and other, and severities critical to low. Categories and severities are checked against those fixed sets.

5. Positioning is resolved outside the review model

When the agent files a comment, internal/reviewtask/tools.go resolves its line in a fixed order, quoted from the source comment: “the comment’s own file, then a cross-file search, then the LLM”. A comment filed against the wrong file can be re-filed with a comment_refiled warning. Only if both deterministic steps fail does a separate re-location prompt (re_location_task_system.md) ask a model to extract the exact snippet from the diff.

6. A separate model call fact-checks, with a deliberately weak veto

After each round executeGroupReviewFilter runs a filter task. Its prompt (review_filter_task_system.md) is narrow: remove only comments the diff proves factually wrong, and approve when evidence falls short, because “Keeping an incorrect comment costs a reviewer a few seconds of attention” while removing a correct one “silently destroys a real finding”. The filter can be skipped with --no-filter.

7. Rules are matched by path

internal/config/rules/system_rules.json maps globs to rule documents, with default.md as the fallback: **/*.go to go.md, **/*.java to java.md, .github/workflows/**/*.{yaml,yml} to github_workflows.md, and many more. A Go file is reviewed against Go guidance instead of one giant checklist, which keeps the prompt focused.

8. Reviews are resumable and auditable

internal/session records history and a run manifest with per-file coverage (completed, reused, failed with a reason class). Budget exhaustion is treated as controlled truncation, not a run failure. ocr review --from <ref> --to <ref> --resume <session-id> (or the same --commit) picks an interrupted range or commit review back up; the README’s resume examples cover those modes, not workspace reviews.

Delegation: reuse the engineering, borrow someone else’s model

internal/delegate renders the matched rule groups as markdown (“Rule Group N: source / pattern, Applies to: files”). With ocr delegate preview and ocr delegate rule, the host coding agent does the reviewing itself while OCR still decides files and rules. The bundled skills open-code-review and open-code-review-delegate wrap both modes.

Where it sits: other trending code-review tools and skills

Stars below are from the GitHub API on 2026-11-14 and the descriptions are the projects’ own. I did not run these.

• tirth8205/code-review-graph (32.8k, MIT, Python): a local code-intelligence graph for MCP and CLI so AI tools “read only what matters”. It attacks the context-cost side of review.
• The-PR-Agent/pr-agent (16.1k, MIT, Python): “The Original Open-Source PR Reviewer”.
• millionco/react-doctor (15.1k): “Your agent writes bad React. This catches it.” A stack-specific checker.
• anthropics/claude-code-action (9.9k, MIT, TypeScript): a general GitHub Action; its README lists code review next to answering questions and implementing changes.
• modem-dev/hunk (9.8k, MIT): a review-first terminal diff viewer for agentic coders, the human side of the loop.
• anthropics/claude-code-security-review (6.9k, MIT, Python): a security-focused review Action using Claude.
• kodustech/kodus-ai (1.6k): open source, self-hosted review, bring your own LLM.
• hyhmrright/brooks-lint (1.6k, MIT): six Agent Skills for architecture, technical debt, tests and remediation reviews across Codex, Cursor and Copilot.
• HexmosTech/git-lrc (1.5k, Go): micro AI reviews that run on git commit.
• openqodex/openqodex (1.2k, Apache-2.0): a separate reviewer checks every change your coding agent writes, in Claude Code, Codex, Cursor and Cline.
• openqa-cn/codexqa (238, Apache-2.0): 11 local-first Agent Skills including change-impact analysis and AI code review.

Two patterns stand out. One group puts review in the pipeline (Actions, commit hooks, self-hosted servers). The other ships review as portable Agent Skills that run inside the coding agent. OCR is unusual in covering both with the same engine, and in publishing a benchmark: its README cites a set built from 50 open-source repositories and 200 real pull requests (AACR-Bench on Hugging Face) where it reports higher precision and F1 than Claude Code with the same model at roughly one ninth of the tokens, and lower recall.

Takeaways

• Decide in code what a review must cover; let the model decide how deep to look.
• Index-based grouping and a closed comment schema keep model output small and checkable.
• Resolve line positions outside the reviewing model, and give any fact-checker a weak veto.
• Budgets, panic isolation and a coverage manifest turn a flaky agent run into an auditable one.
• Compare tools by where they run (CI, commit hook, inside the agent) and by whether they report precision as well as recall.

Want an AI review gate set up for your team’s pull requests? Talk to Cui.Guru.