Open-Code-Review Architecture: Inside Alibaba's Modular Go CLI

Open-code-review architecture consists of four tightly-coupled layers—CLI dispatch, domain logic, runtime engine, and supporting services—that orchestrate deterministic file selection and LLM-powered code reviews through a Cobra-based Go CLI.

The open-code-review architecture follows a modular design pattern that separates deterministic engineering concerns from dynamic AI operations. Developed by Alibaba as a Go-based CLI tool, the codebase structures functionality into distinct layers responsible for command routing, review orchestration, manifest tracking, and auxiliary services. This architectural separation ensures that the LLM never decides which files to review; instead, the CLI maintains hard-constraint coverage through deterministic selection and rule resolution.

CLI Entry Point and Command Dispatch

The architecture centers on Cobra for command parsing and dispatch. The root.go file in cmd/opencodereview/ defines the top-level ocr command and registers all sub-commands through rootCmd.AddCommand().

rootCmd.AddCommand(versionCmd)      // ocr version
rootCmd.AddCommand(reviewCmd)       // ocr review
rootCmd.AddCommand(scanCmd)         // ocr scan
rootCmd.AddCommand(delegateCmd)     // ocr delegate …
rootCmd.AddCommand(sessionCmd)      // ocr session …
rootCmd.AddCommand(configCmd)       // ocr config …
rootCmd.AddCommand(viewerCmd)       // ocr viewer

Source: [cmd/opencodereview/root.go](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/root.go)

This layer handles user input parsing, version output, and routes execution to the appropriate domain command handler.

Domain Logic Layer

The domain logic implements six primary commands, each residing in its own file within cmd/opencodereview/. These handlers bridge CLI arguments to the runtime engine.

Review and Scan Commands

The review command drives the core AI-powered workflow. It reads Git diffs, resolves target files, and invokes the LLM agent to generate line-level comments. Implementation resides in cmd/opencodereview/review_cmd.go.

The scan command performs full-file scans without Git diff constraints, designed for auditing unfamiliar codebases. This logic lives in cmd/opencodereview/scan_cmd.go.

Delegation and Session Management

The delegate command switches the tool into Delegation Mode, where an external coding agent executes the review while open-code-review handles only deterministic selection and rule resolution. See cmd/opencodereview/delegate_cmd.go.

The session command persists run states—manifests, checkpoints, and comments—to ~/.ocr/sessions/. It enables resume functionality and historical inspection via ocr session list and ocr session comments. Implementation is in cmd/opencodereview/session_cmd.go.

Configuration and Viewer

The config command manages provider selection (Claude, Codex, Cursor), API key storage, and runtime options through a JSON configuration at $HOME/.ocr/config.json.

The viewer command launches an embedded HTTP server for browsing review results in a browser, implemented across cmd/opencodereview/viewer_cmd.go and internal/viewer/server.go.

Runtime Engine: The ManifestBuilder

The ManifestBuilder in internal/session/manifest.go forms the deterministic core of the open-code-review architecture. It tracks coverage, persists run manifests, and enforces the constraint that file selection remains strictly deterministic.

• Item Identification: The ItemID(operation, mode, oldPath, newPath) function generates stable hashes that survive resume cycles.
• Lifecycle Methods: The builder follows a strict sequence: RegisterSelected → SealSelected → Mark* (Completed/Failed/Waived) → Finalize.
• Failure Handling: Per-item FailureClass and run-level RunFailureClass categorize failures (provider errors, timeouts) in the final RunManifest.

The builder uses a mutex for concurrent-safety and maintains idempotency—re-applying the same outcome does not corrupt state.

Supporting Services

Four service categories support the core workflow:

• Viewer (internal/viewer/server.go): Serves static assets and HTML templates while enforcing host-header allowlists to prevent DNS-rebinding attacks.
• Telemetry (internal/telemetry/*): Emits OpenTelemetry spans and metrics integrated with the manifest lifecycle.
• Toolset (internal/tool/*): Provides utilities for code search, comment collection, file reading, and diff handling that the LLM agent invokes during reviews.
• Session Persistence (internal/session/*): Stores run manifests and checkpoints under the user's session directory.

Execution Flow Example

A typical review workflow demonstrates how the architectural layers interact:

1. CLI parses ocr review and invokes reviewCmd from cmd/opencodereview/review_cmd.go.
2. Git diff generation feeds target files to ManifestBuilder.RegisterSelected.
3. SealSelected locks the denominator, establishing the coverage boundary.
4. The LLM agent receives per-file prompts and requests additional context via the toolset.
5. The CLI calls MarkCompleted, MarkFailed, or MarkWaived for each file based on agent results.
6. Finalize produces a JSON RunManifest persisted to the session store.
7. Optionally, viewerCmd launches the embedded server, loading the manifest to display grouped comments and severity statistics.

# Configure a provider

ocr config provider

# Run review on current workspace

ocr review

# View results in browser

ocr viewer  # starts http://localhost:8080

Summary

• Four-layer architecture: CLI dispatch, domain logic, runtime engine (ManifestBuilder), and supporting services.
• Deterministic coverage: The ManifestBuilder enforces hard constraints on file selection, ensuring the LLM only reviews CLI-selected files.
• Command modularity: Each command (review, scan, delegate, session, config, viewer) resides in dedicated files under cmd/opencodereview/.
• State management: Sessions persist to ~/.ocr/sessions/ with idempotent, concurrent-safe manifest operations.
• Extensibility: The toolset and telemetry layers allow integration with multiple LLM providers and observability platforms.

Frequently Asked Questions

What is the ManifestBuilder in open-code-review architecture?

The ManifestBuilder is the deterministic core located in internal/session/manifest.go that tracks which files are selected for review and their eventual outcomes. It generates stable ItemID hashes for each file and maintains lifecycle state through methods like RegisterSelected, SealSelected, and Finalize, ensuring complete auditability of the review process.

How does open-code-review architecture support multiple LLM providers?

The architecture abstracts provider configuration through the config command and domain logic layer. The cmd/opencodereview/config_cmd.go handles interactive provider selection (Claude, Codex, Cursor) and API key storage in $HOME/.ocr/config.json. The runtime engine remains provider-agnostic, treating the LLM as an external agent that receives prompts and returns structured comments.

What is Delegation Mode in the open-code-review architecture?

Delegation Mode, implemented in cmd/opencodereview/delegate_cmd.go, is an architectural variant where open-code-review performs only deterministic file selection and rule resolution while handing actual review execution to an external coding agent. This mode separates concerns when users want to use their own AI agents while retaining open-code-review's coverage tracking and manifest generation.

How does the viewer component work within the open-code-review architecture?

The viewer is a supporting service that launches an embedded HTTP server via internal/viewer/server.go. It serves HTML templates and static assets to display review sessions, grouping comments by file and showing severity statistics. The server includes security measures such as host-header allowlists to prevent DNS-rebinding attacks, and it reads persisted manifests from the session store to render historical review data.

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