OpenCodeReview Scan vs Review: Understanding the Difference Between OCR Commands

The scan command performs full-file analysis without Git diffs, while the review command analyzes only code changes between Git references, making them suited for repository audits versus traditional code reviews.

OpenCodeReview (OCR) from Alibaba provides two distinct entry points for code analysis: ocr scan and ocr review. While both leverage the same LLM runtime and telemetry infrastructure, the difference between scan and review commands in OpenCodeReview lies in their file selection strategy and review scope. Understanding these distinctions ensures you choose the right tool for full-repository audits or targeted change validation.

Core Architectural Differences

Purpose and Workflow

The scan command executes a full-file scan across the working tree, reading every specified file directly from disk and sending complete contents to the LLM. It requires no Git diff or version control context, making it ideal for auditing entire repositories, generated files, or arbitrary path lists.

The review command operates as a diff-based review system, examining only changes between two Git references (such as commits, branches, or the current staged state). This mimics traditional pull request workflows by focusing exclusively on what has changed rather than the entire codebase.

Entry Points and Implementation

According to the alibaba/open-code-review source code, each command has a dedicated implementation file:

• Scan: Implemented in cmd/opencodereview/scan_cmd.go as the scanCmd Cobra command with Use: "scan". It instantiates the agent via scan.NewAgent located in internal/scan/provider.go.

• Review: Implemented in cmd/opencodereview/review_cmd.go as the reviewCmd Cobra command with Use: "review". It uses agent.New from internal/agent/agent.go to create the review agent.

Technical Implementation Details

Template Loading and Configuration

Each command loads distinct template configurations that dictate prompts, token budgets, and file-size limits.

The scan command calls template.LoadScanDefault() from internal/config/template/scan_template.go to load scan-specific parameters. This template defines how the LLM should process complete files rather than patches.

The review command re-uses the diff-review template attached to the common context (cc.Template), which is optimized for analyzing code changes and patches.

File Reading Modes

File access patterns differ significantly between the two commands:

• Scan: Uses tool.FileReader with Mode: tool.ModeWorkspace, reading files directly from the working directory without Git integration.

• Review: Utilizes tool.ParseReviewMode to dynamically select between tool.ModeWorkspace, tool.ModeRange, or tool.ModeCommit, passing the appropriate Ref to FileReader based on the --from, --to, or --commit flags specified.

Tool Set Configuration

The commands diverge in available toolsets provided to the LLM:

• Scan: Explicitly excludes the file_read_diff tool via excludeToolDef(rt.MainToolDefs, "file_read_diff") because no diff context exists.

• Review: Includes the full toolset, encompassing both file_read (defined in internal/tool/file_read.go) and file_read_diff (defined in internal/tool/file_read_diff.go), along with any MCP-provided tools.

Command-Line Usage and Flags

Scan Command Options

The scan command targets comprehensive file analysis with flags tailored for bulk operations:

# Scan entire repository excluding generated files

ocr scan \
    --path . \
    --exclude '**/generated/*,**/testdata/*' \
    --output-format json

# Scan specific files with token budget

ocr scan \
    --path internal/agent/agent.go,internal/mcp/client.go \
    --max-tokens-budget 8000 \
    --preview

Key flags include --path for targeting specific files, --exclude for pattern-based exclusion, --max-tokens-budget for controlling LLM costs, and --resume for continuing previous scan sessions.

Review Command Options

The review command focuses on Git-aware change detection:

# Review current workspace changes (staged/unstaged)

ocr review \
    --exclude '**/generated/*' \
    --format json

# Review changes between branches

ocr review \
    --from master \
    --to feature-xyz \
    --background "Focus on security changes"

# Review specific commit

ocr review \
    --commit a1b2c3d4 \
    --background-file ./docs/requirements.md

Key flags include --from and --to for range specifications, --commit for single-commit analysis, and --background or --background-file for providing additional context to the LLM.

Resume and Session Management

Both commands support resumable operations but handle session state differently:

• Scan Resume: Uses loadScanResumeState to continue a previous full-file scan via --resume <session-id>, maintaining the file queue and processed state.

• Review Resume: Uses loadReviewResumeState to resume a previous range review, requiring the original --from/--to or --commit parameters to reconstruct the diff context.

Summary

• Scan operates on complete files without Git diff context, suitable for repository-wide audits and static analysis.
• Review analyzes Git diffs between references, optimized for pre-commit and pull request validation workflows.
• Implementation: Scan resides in cmd/opencodereview/scan_cmd.go using internal/scan, while Review resides in cmd/opencodereview/review_cmd.go using internal/agent.
• Tooling: Scan excludes file_read_diff; Review includes it along with full Git range parsing capabilities.
• Templates: Scan uses dedicated scan templates; Review uses diff-optimized templates from the common context.

Frequently Asked Questions

When should I use ocr scan instead of ocr review?

Use ocr scan when you need to analyze entire files rather than changes, such as auditing a complete codebase for security vulnerabilities, scanning generated files or fixtures, or running one-off static analysis passes without Git context. Use ocr review when validating specific changes in a commit, branch comparison, or staged changes before committing.

Can I resume an interrupted scan or review session?

Yes. Both commands support resumable sessions via the --resume flag. For scans, specify --resume <session-id> to continue from loadScanResumeState. For reviews, use --resume with the original --from/--to or --commit parameters to restore the range state via loadReviewResumeState.

Why does the scan command exclude the file_read_diff tool?

The scan command excludes file_read_diff (via excludeToolDef(rt.MainToolDefs, "file_read_diff")) because it operates in ModeWorkspace, reading complete files directly from disk without computing or requiring Git diffs. The file_read_diff tool is only relevant for the review command, which must parse changes between Git references.

How do I review changes between two specific branches?

Use the ocr review command with the --from and --to flags to specify the base and target references. For example: ocr review --from master --to feature-branch. This invokes tool.ParseReviewMode with ModeRange to analyze only the diff between those branches, providing focused feedback on the changes rather than the entire codebase.

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