Main Components of the Open-Code-Review System: Architecture Deep Dive

The open-code-review system combines deterministic file selection with LLM-driven analysis through ten specialized Go packages spanning CLI parsing, agent orchestration, diff resolution, and MCP extensibility.

The alibaba/open-code-review repository implements an AI-powered code review CLI that marries deterministic engineering with large-language-model capabilities. Understanding the main components of the open-code-review system is essential for extending the tool or optimizing review workflows. The codebase is organized into clearly scoped packages under cmd/ and internal/, each handling specific responsibilities from Git diff parsing to session persistence.

CLI Entry Point and Command Parsing

The CLI layer (cmd/…) serves as the user-facing entry point, parsing commands and loading common context before kicking off the review workflow.

In cmd/opencodereview/review_cmd.go, the review command initializes the entire pipeline:

# Review all staged, unstaged and untracked changes in the current repo

ocr review

This command loads the common context, builds the tool registry, creates the LLM runtime, and hands control to the agent orchestrator. The CLI also handles configuration commands for setting up LLM providers:

# Choose a built-in provider (e.g. OpenAI) and a model

ocr config provider   # interactive UI

ocr config model

Core Review Agent and Orchestration

The Agent (internal/agent) functions as the central orchestrator that drives the entire review process. Located in internal/agent/agent.go, this component selects files, applies deterministic rules, drives the LLM, and collects generated comments.

The agent bridges the deterministic core (file selection and rule matching) with the dynamic LLM core (adaptive reasoning and prompt generation). It coordinates between the diff engine to identify targets, the tool registry to provide context, and the LLM runtime to generate feedback.

LLM Runtime and Provider Management

The LLM Runtime (internal/llm) handles provider initialization, client creation, and prompt-template engineering. The internal/llm/runtime.go file loads the configured LLM provider and supplies the template engine used by the agent.

This abstraction allows the system to support multiple providers (such as OpenAI) through a unified interface. Configuration files read by this runtime determine which model and endpoint the agent uses during reviews.

Diff Engine and File Resolution

The Diff Engine (internal/diff) parses Git diffs and resolves moved or renamed files to produce the definitive list of files requiring review. The internal/diff/resolver.go file implements the logic that transforms raw Git output into structured file selections.

This deterministic component ensures that the agent only analyzes relevant changes, filtering out noise while handling complex Git scenarios like file renames and patch sets.

Tool Registry for LLM Function Calling

The Tool Registry (internal/tool) supplies the LLM with a curated set of tool-call definitions that extend its capabilities beyond text generation. The internal/tool/file_read.go file implements tools like file_read that allow the LLM to inspect source code during the review process.

These tools provide deterministic capabilities—such as reading files, searching codebases, and analyzing diffs—that the LLM can invoke through structured function calling.

MCP Integration for External Tool Servers

The MCP Integration (internal/mcp) connects to external Model-Centered-Programming servers that expose additional tools to the agent. Implemented in internal/mcp/client.go, this client discovers and registers remote tool definitions with the LLM runtime.

This extensibility mechanism allows teams to integrate custom static analysis tools or proprietary linters without modifying the core codebase:

# Start an MCP server that implements a custom tool (e.g. static analysis)

ocr delegate preview   # OCR will discover the tool through mcp.CollectToolDefs()

Session Management and State Persistence

The Session Management (internal/session) component persists review state, supports resume/replay functionality, and stores generated comments. The internal/session/persist.go file handles serialization of review sessions to disk.

Users can interact with saved sessions through the CLI:

# List saved sessions

ocr session list

# Print the comments of a specific session in JSON

ocr session comments <session-id> --json

This enables long-running reviews, historical analysis, and integration with CI/CD pipelines that need to reference previous review states.

Web-Based Viewer Interface

The Viewer (internal/viewer) serves a lightweight web UI that visualizes sessions and comment locations. Implemented in internal/viewer/server.go, this HTTP server renders the session data managed by the persistence layer.

The viewer provides a browser-based interface for exploring AI-generated comments, making it easier to navigate complex reviews across large codebases.

Telemetry and Observability

The Telemetry (internal/telemetry) component emits OpenTelemetry spans, metrics, and shutdown traces for comprehensive observability. The internal/telemetry/provider.go file configures the OpenTelemetry exporter setup.

This ensures that review performance, LLM latency, and error rates are visible to operators running the tool in production environments.

Configuration and Rule Matching

The Configuration & Rules (internal/model) package holds the rule-matching logic that deterministically selects which files a review applies to. The internal/model/review.go file defines the data structures and matching algorithms used by the agent to filter files based on path patterns, file types, or custom criteria.

This deterministic pre-filtering ensures that specific rules—such as security checks for authentication code or style checks for configuration files—target only the relevant portions of the codebase.

Summary

• The CLI (cmd/opencodereview/review_cmd.go) parses commands and initiates the review workflow.
• The Agent (internal/agent/agent.go) orchestrates file selection, rule application, and LLM interaction.
• The LLM Runtime (internal/llm/runtime.go) manages provider initialization and prompt templating.
• The Diff Engine (internal/diff/resolver.go) parses Git diffs and resolves file movements.
• The Tool Registry (internal/tool/file_read.go) provides deterministic tools for the LLM to inspect code.
• MCP Integration (internal/mcp/client.go) enables external tool servers to extend capabilities.
• Session Management (internal/session/persist.go) enables persistence, resume, and replay of reviews.
• The Viewer (internal/viewer/server.go) exposes a web interface for comment visualization.
• Telemetry (internal/telemetry/provider.go) provides OpenTelemetry observability.
• Configuration (internal/model/review.go) implements deterministic rule matching for file selection.

Frequently Asked Questions

What is the role of the Agent component in open-code-review?

The Agent acts as the central orchestrator located in internal/agent/agent.go that coordinates the entire review lifecycle. It selects files using the diff engine, applies deterministic rules from the configuration layer, drives the LLM runtime with prompts and tool access, and aggregates the resulting comments into a coherent review output.

How does the Diff Engine determine which files to review?

The Diff Engine, implemented in internal/diff/resolver.go, parses Git diffs to identify staged, unstaged, and untracked changes. It resolves moved or renamed files and filters the repository contents to produce a definitive list of targets, ensuring the agent only analyzes code that has actually changed.

What is MCP integration and how does it extend the system?

MCP (Model-Centered-Programming) integration, found in internal/mcp/client.go, allows open-code-review to connect to external tool servers that expose additional capabilities. Through the mcp.CollectToolDefs() function, the system discovers and registers remote tools—such as custom static analyzers—making them available to the LLM without modifying core source code.

How does session management support CI/CD workflows?

The Session Management component in internal/session/persist.go serializes review states to disk, enabling commands like ocr session comments <session-id> --json to retrieve historical results. This persistence allows CI pipelines to reference previous review outputs, audit AI-generated suggestions, and resume interrupted reviews without re-processing unchanged code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}