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

> Learn to use Open Code Review's session resume feature to pick up interrupted reviews without re-scanning files. Save time and effort with the --resume flag.

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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:

```bash

# 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:

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

```

### Single-Commit Example

```bash

# 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`](https://github.com/alibaba/open-code-review/blob/main/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:

```bash

# ❌ 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`](https://github.com/alibaba/open-code-review/blob/main/internal/session/resume.go) – Core resume logic: loads manifests, validates compatibility, merges checkpoints
- [`internal/session/persist.go`](https://github.com/alibaba/open-code-review/blob/main/internal/session/persist.go) – Manifest serialization with fields like `resumedFrom` and `reused_files`
- [`plugins/open-code-review/opencode/open-code-review.ts`](https://github.com/alibaba/open-code-review/blob/main/plugins/open-code-review/opencode/open-code-review.ts) – CLI flag parsing and mutual-exclusion enforcement
- [`cmd/opencodereview/review_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/review_cmd.go) – Command orchestration that delegates to session-resume handlers
- [`pages/src/content/docs/en/cli-reference.md`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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`](https://github.com/alibaba/open-code-review/blob/main/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.