Why AI Code Review Needs a System
OpenCodeReview is an AI-powered code-review CLI and integration framework. This opening asks a specific question about it: why does the project put so much review logic outside the language model? The answer supports a practical judgment for the rest of this series: a useful AI review is not just a smart response to a diff, but a controlled path from a known change to a location you can act on, with its limits still visible.
That distinction matters because software review has two different kinds of work. One is interpretive: does this change create a security problem, violate an invariant, or fail to meet the requirement? The other is procedural: which files count, what version of each file should be read, where can a finding be attached, and what happened when part of the run stopped? A language model can contribute to both, but it is a poor place to hide decisions that must remain stable from run to run.
A conventional code-review result often makes those layers look like one thing. A reviewer sees a comment attached to a line and has to infer whether the system examined the whole change, whether the line was actually changed, whether the model read surrounding files, and whether other files were skipped because of a limit. OpenCodeReview treats those as separate engineering questions. That separation is what makes its design worth studying: the project is trying to make an AI judgment useful inside a software process, not merely impressive in a conversation.
OpenCodeReview is more than a model wrapper
At the surface, OpenCodeReview reads Git changes, sends selected material to a configurable LLM, and returns structured review comments. Its normal review command works on a workspace, a commit, or a branch range. It also has a scan mode for auditing whole files when there is no useful diff. A finding can include a code excerpt, a suggested change, a severity, and a path and line range that downstream tools can use.
That description is accurate, but incomplete. Before the model reviews anything, OCR constructs a diff, removes files outside its review policy, resolves rules for the surviving files, and forms bounded review units. During and after model execution, it manages tools, token pressure, comment location, and persisted session state. The model is therefore one participant in a larger system rather than the system's sole source of truth.
This matters in a realistic change. A pull request might alter an API handler, a service, a configuration file, and a generated artifact at the same time. A model can reason about the relationship between the handler and service, but that does not mean the generated artifact should consume the same attention, or that a test file excluded by policy should be silently counted as reviewed. The engineering layer establishes those distinctions before the model's attention is spent.
The project presents this architecture as the result of experience with a practical failure: general-purpose agents can cut corners on large changesets, drift away from the actual code location, and change quality when natural-language instructions change slightly. These are not all failures of code comprehension. A model may understand a function and still fail to review the rest of the change, point to a stale line, or silently stop when its context becomes crowded.
OpenCodeReview's response is to make the review path explicit. Deterministic engineering handles decisions that should not depend on a model's mood: file selection, rule matching, semantic grouping limits, and comment positioning. The agent handles decisions that benefit from flexible reasoning: which surrounding code to read, how to connect related changes, and whether a change appears risky. This is the project's central design idea—deterministic engineering around agent judgment—not a claim that the model itself becomes deterministic.
The difference is visible in the boundary between “read more context” and “review more files.” OCR can give the agent tools to search the repository or inspect another changed file, but those tools do not turn every discovery into a new comment target. The agent's flexibility is useful precisely because it operates inside a review unit with an explicit scope.
Why a capable agent still needs hard boundaries
Imagine asking a general-purpose coding agent to review a large pull request in one conversation. It may begin with the most interesting file, spend too long exploring a dependency, or use a checklist that quietly becomes its definition of “done.” If the prompt asks for line-level comments, it may produce a plausible line number without proving that the line belongs to the current diff. The problem is not simply that the model lacks intelligence. The workflow gives it too many opportunities to decide what correctness means.
There is also a difference between a correct observation and a usable review artifact. “This validation is missing” may be a valuable thought, but the team needs to know which changed code demonstrates the problem, whether the issue is in the current patch or only in an unchanged caller, and whether the proposed location will survive a platform's inline-comment rules. If those transformations are left to free-form language, a good analysis can still become a misleading review.
OCR divides that responsibility. It can determine exactly which files are eligible before an LLM call, and its preview path uses the same selection result as a real review. It can group related files so a handler and its service are not necessarily judged in isolation, while still limiting group size and falling back when grouping fails. It can resolve a comment from the code snippet the model supplied instead of accepting an unsupported location as fact. These controls do not decide whether a finding is important. They make the finding's scope and location testable.
This is also why the project does not reduce its agent to a static rule engine. Code review is full of relationships that are awkward to enumerate in advance: a new call may change an assumption in a nearby implementation, a configuration change may affect a provider path, and a requirement may give ordinary-looking code unusual significance. The agent can retrieve context and form a judgment where a fixed pattern matcher would be too narrow. The surrounding engineering determines where that judgment applies and what happens when the model cannot complete the path.
The result is best understood as a controlled division of labor:
- Engineering establishes the review boundary. It decides what change and file set are in scope, which rules apply, how much context a unit can carry, and whether a proposed location can be grounded in code.
- The agent explores and interprets. It reads permitted context, reasons about behavior, and calls the comment tool when it has a finding worth reporting.
- The output pipeline preserves uncertainty. A comment that cannot be anchored can remain a summary finding rather than becoming a confidently misplaced inline note; a skipped or failed unit can remain visible rather than disappearing into a clean-looking result.
This division also gives the team different places to improve the system. If a file is never selected, the problem belongs to scope or policy. If selected files are grouped badly, the system can change its grouping fallback without pretending the model discovered a fact. If the model identifies a real issue but the comment lands on the wrong line, positioning can be repaired independently of the model's reasoning. The architecture does not eliminate failure; it makes failure attributable.
The project reports a deliberate quality trade-off alongside this design. Its README describes a benchmark built from 50 open-source repositories, 200 real pull requests, ten programming languages, more than 80 senior-engineer validators, and 1,505 annotated issues. It reports higher precision and F1, lower token use, and faster completion than a general-purpose Claude Code setup using the same underlying model, while also acknowledging lower recall. Those are first-party benchmark claims; the retained material does not include the full analysis or an independent replication. Their most useful meaning here is not “OCR always wins,” but that OCR chooses a visible operating point: fewer noisy findings and bounded cost over maximal issue discovery.
That choice changes how a reader should interpret silence. “No comments” can mean a clean review, but it can also coexist with excluded files, a size limit, an interrupted group, or a model that did not finish. Trust therefore cannot come from the comment count alone. It has to come from the path that produced the count and the record of what that path covered.
The human decision is still part of the design
OpenCodeReview's own boundary is equally important at the other end of the pipeline. The project describes itself as a review tool, not an autonomous merge system or a general-purpose coding assistant. Its roadmap says that automated fixing without human review is out of scope, and its retrospective describes a workflow in which AI writes and reviews code while people inspect the result and make final calls.
That is not merely a cautious disclaimer. Review comments are judgments under incomplete context, and a suggestion that is locally sensible can still conflict with product requirements, deployment constraints, or an intentional compatibility choice. The system can make the evidence easier to inspect, but it cannot know every organizational reason behind a change. Keeping approval with a human is therefore consistent with the same boundary discipline that governs file selection and comment placement: the system should make its basis visible without pretending that visibility removes judgment.
Some host integrations choose different defaults. A Claude Code command can be configured to auto-fix selected findings, while an agent skill can ask before changing code. That difference belongs to the calling workflow, not to a hidden promise that OCR has proved the fix safe. The core system supplies evidence and structured judgments; a team still decides whether a finding is correct, whether a suggestion fits the requirement, and whether the change should be merged.
So the central question for this series is not whether OpenCodeReview can replace a reviewer. It is more precise: can a team make AI review useful by controlling the parts that must be stable, giving the model freedom where interpretation is valuable, and keeping omissions and uncertainty observable? To answer it, the next step is to examine the first boundary in that system: what exact Git change does OpenCodeReview treat as authoritative when a workspace is moving or a branch contains unrelated history?