How to Use the Session Resume Feature for Interrupted Reviews in Open Code Review

Open Code Review (OCR) can resume interrupted range or single-commit reviews without re-scanning already processed files by reusing a persisted JSON manifest via the --resume flag.

The --resume feature in Alibaba's Open Code Review CLI allows developers to recover from unexpected interruptions—such as process termination, machine reboots, or manual aborts—without losing progress on large code reviews. This capability is essential for long-running reviews of extensive commit ranges, ensuring efficient use of compute resources and consistent final results.

When Session Resume Is Available

The resume mechanism operates under strict constraints. It only works for two review modes:

• Range reviews: --from <commit> --to <commit>
• Single-commit reviews: --commit <hash>

It is incompatible with:

• Full workspace scans (ocr review .)
• The --preview flag (preview mode)

Attempting to combine these will trigger validation errors in the CLI parser.

How the Resume Mechanism Works

When a review completes or checkpoints, OCR writes a JSON manifest via internal/session/persist.go. This manifest contains:

• session_id – unique identifier for the review session
• review_mode – either range or commit
• The exact range or commit under examination
• Processed files list and model checkpoints

On resume, internal/session/resume.go executes a four-step validation and recovery process:

1. Load the existing manifest from disk using the provided session ID
2. Verify that the new request matches the original mode and range/commit—mismatches abort with an error
3. Reuse previously processed files, scanning only remaining items
4. Update the manifest with new checkpoints for potential future resumptions

This incremental approach ensures no duplicate work while maintaining review consistency.

Starting and Resuming a Review

Range Review Example

Begin by capturing the session ID from JSON output:

# Start a range review

ocr review --from main --to feature-branch --output=json > review-output.json

# Extract session_id from output, e.g., "abcd1234"

After interruption, resume with the same range and session ID:

ocr review --from main --to feature-branch --resume abcd1234

Single-Commit Example

# Initial commit review

ocr review --commit a1b2c3d --output=json > commit-output.json

# → session_id: "sess-5678"

# Resume later

ocr review --commit a1b2c3d --resume sess-5678

Common Errors and Their Causes

The command-line parser in plugins/open-code-review/opencode/open-code-review.ts enforces mutual exclusion rules. Two specific error messages indicate flag misuse:

Error Message	Cause
'resume' cannot be combined with 'commit' or a 'from'/'to' range.	Passing a different --commit or range than the original session
'preview' and 'resume' cannot be used together.	Including --preview with --resume

Example of an invalid command:

# ❌ WRONG: new range does not match original session

ocr review --from dev --to hotfix --resume abcd1234

# → Error: 'resume' cannot be combined with 'commit' or a 'from'/'to' range.

Key Source Files

Understanding the implementation helps debug resume issues:

• internal/session/resume.go – Core resume logic: loads manifests, validates compatibility, merges checkpoints
• internal/session/persist.go – Manifest serialization with fields like resumedFrom and reused_files
• plugins/open-code-review/opencode/open-code-review.ts – CLI flag parsing and mutual-exclusion enforcement
• cmd/opencodereview/review_cmd.go – Command orchestration that delegates to session-resume handlers
• pages/src/content/docs/en/cli-reference.md – Official documentation of --resume constraints

Summary

• Session resume enables recovery from interrupted range or single-commit reviews without duplicate file scanning
• Capture the session_id from initial JSON output to enable future resumption
• Match original parameters exactly—mode, range, or commit hash must remain consistent
• Avoid --preview and workspace scans when planning to use resume functionality
• Manifest persistence in internal/session/persist.go ensures state durability across process restarts

Frequently Asked Questions

What happens if I change the commit range when resuming?

OCR aborts immediately with the error 'resume' cannot be combined with 'commit' or a 'from'/'to' range. The resume logic in internal/session/resume.go validates that the new invocation matches the original session's parameters. Changing the range would create an inconsistent review state, so the tool prevents this operation.

Can I resume a review on a different machine?

Yes, provided the manifest file is accessible. The session ID references a JSON manifest stored on disk. If you transfer this file or use shared storage, resumption works across machines. The verification depends solely on matching session metadata, not machine-specific identifiers.

Why does --preview block resume functionality?

Preview mode generates temporary output without persisting review state. Since --resume relies on the manifest written by internal/session/persist.go, and preview skips this persistence step, the two flags are mutually exclusive. This enforcement occurs in plugins/open-code-review/opencode/open-code-review.ts.

How does OCR handle partially processed files?

The manifest tracks individual file checkpoints. When resuming, internal/session/resume.go identifies completed files by their presence in the reused_files list and excludes them from the new scan. Only files without recorded checkpoints are processed, ensuring complete coverage without redundancy.

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