open-code-review

Open Code Review — routing-first AI review via the ocr CLI

Keyword: open-code-review · ocr review · ocr scan

OpenCodeReview (OCR) is an open-source AI code-review CLI from Alibaba. It reads Git diffs (or whole files) and produces structured, line-level review comments through a configured LLM.

This skill is the operator front door for the ocr binary: it decides the lightest invocation that answers the user's question, supplies business context, classifies the findings, and only then applies fixes. It does not re-implement human review judgment — that lives in the neighboring code-review skill.

When to use this skill

• The user wants an automated review of working-copy changes, a commit, a branch range, or a PR/MR
• The user wants to scan whole files (no diff) to audit an unfamiliar or pre-migration codebase
• The user wants the review wired into a coding agent (Claude Code / Codex slash command) or CI/CD
• The user needs help configuring the ocr LLM provider or testing connectivity
• The user wants OCR comments classified by priority and selectively auto-fixed

When NOT to use this skill

• Evidence-first human review judgment (approve / request-changes / block reasoning) → code-review
• Splitting commits, rebasing, conflict resolution, push recovery → git-workflow
• Reproducing or isolating a live runtime failure → debugging
• Long-term coverage policy, CI gates, flaky-suite direction → testing-strategies
• Measurement-led bottleneck analysis → performance-optimization

Instructions

Step 1: Confirm prerequisites before reviewing

which ocr || echo "NOT INSTALLED"   # CLI present?
ocr llm test                        # LLM reachable?

If ocr is missing, install only what the environment needs:

bash scripts/install.sh --method npm         # global npm install (default)
bash scripts/install.sh --method release     # GitHub release binary (macOS/Linux)
bash scripts/install.sh --method source      # build from source with make

If ocr llm test fails, the user must configure a provider. Never invent or hardcode an API key — stop and ask the user for credentials, then use one path:

# Interactive (recommended for humans)
ocr config provider
ocr config model

# Non-interactive (CI/scripts) — built-in provider
ocr config set provider anthropic
ocr config set providers.anthropic.api_key <api-key>
ocr config set providers.anthropic.model claude-sonnet-4-6

# Environment variables (highest priority — best for CI)
export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=<api-key>
export OCR_LLM_MODEL=claude-opus-4-6
export OCR_USE_ANTHROPIC=true

Provider/config details live in references/configuration-and-rules.md.

Step 2: Gather business context before invoking

Read the commit messages, branch name, or the user's stated intent and distill one short requirement sentence. Pass it through --background (-b) — OCR uses it to judge whether the change implements the requirement, not just whether the code parses.

Step 3: Choose the lightest invocation that fits

Pick exactly one primary mode:

User intent	Command
Review the working copy (staged + unstaged + untracked)	bash scripts/run-review.sh -b "context"
Review a single commit	bash scripts/run-review.sh --commit <sha> -b "context"
Compare two refs (PR / feature branch)	bash scripts/run-review.sh --from <base> --to <head> -b "context"
Dry-run: which files would be reviewed	ocr review --preview
Audit whole files with no meaningful diff	bash scripts/run-scan.sh --path <dir>

The wrapper scripts default to --audience agent, which suppresses progress UI and emits only the final summary — the right mode when an agent (not a human terminal) consumes output.

# Workspace review with context
bash scripts/run-review.sh -b "Adding rate limiting to the login API"

# Branch range, JSON output for parsing, lower concurrency to dodge rate limits
bash scripts/run-review.sh --from origin/main --to feature-x --format json --concurrency 4

# Single commit; --background auto-fills from the commit message when omitted
bash scripts/run-review.sh --commit abc123

# Full-file scan of a subdirectory, capped spend, skipping generated/test files
bash scripts/run-scan.sh --path internal --exclude '**/*_test.go,**/generated/**' --max-tokens-budget 500000

Review/scan flag references live in references/intake-and-modes.md.

Step 4: Classify and report findings

OCR returns comments with path, content, start_line/end_line (both 0 = positioning failed), optional suggestion_code, existing_code, and thinking. Group them by priority:

• High — obvious bugs, security issues, clear mistakes, or well-founded fixes with a precise proposal
• Medium — reasonable but context-dependent concerns, style/perf suggestions, manual-fix items
• Low — likely false positives, missing context, nitpicks — discard silently unless the user wants everything

Report High and Medium grouped by level; cite path:line for each.

Step 5: Fix only with intent and verification

• If the user explicitly asked to "review and fix", apply High/Medium fixes directly when safe and well-defined
• If the user only asked to "review", ask before changing any code
• For complex fixes needing manual work, describe what must be done instead of guessing
• Always re-run the relevant tests/build and confirm fixes with the user before committing

Step 6: Wire OCR into agents or CI when asked

• Skill install: npx skills add alibaba/open-code-review --skill open-code-review
• Claude Code plugin: /plugin marketplace add alibaba/open-code-review then /plugin install open-code-review@open-code-review
• Codex plugin: codex plugin marketplace add alibaba/open-code-review, then /plugins to enable
• CI/CD: ocr review --from "origin/main" --to "<commit_sha>" --format json (use a commit SHA for --to so fork PRs resolve)

Plugin and CI wiring details live in references/cicd-and-plugins.md.

Output format

When asked to review, return a compact, priority-grouped brief:

## Code Review Results

**Mode**: workspace | commit <sha> | <base>..<head> | scan
**Files reviewed**: N
**Issues**: X high / Y medium

### High priority
- **`path/to/file.go:42`** — what is wrong
  > Recommendation: how to fix

### Medium priority
- **`path/to/other.ts:88`** — concern + context

### Decision
- ran <command>; fixes applied | fixes proposed (awaiting approval) | route-out to <skill>

Examples

Example 1: "Review my changes"

Run bash scripts/run-review.sh -b "<context>" (workspace mode), then classify and report.

Example 2: "Review this PR against main"

Run bash scripts/run-review.sh --from origin/main --to <branch> -b "<context>".

Example 3: "Audit this unfamiliar repo for issues"

Use bash scripts/run-scan.sh --preview first to see the file list and token estimate, then scan.

Example 4: "Review commit abc123 and fix the high-confidence bugs"

Run bash scripts/run-review.sh --commit abc123, apply only High findings with precise fixes, verify, confirm.

Example 5: "Add OCR to our GitHub Actions"

Route to references/cicd-and-plugins.md; use ocr review --from origin/main --to <sha> --format json.

Example 6: "Help me decide whether to approve this risky migration"

That is review judgment, not tooling — run OCR for signal, then route the decision to code-review.

Best practices

1. Confirm ocr is installed and ocr llm test passes before promising a review.
2. Always pass --background context when you can infer it — it materially improves relevance.
3. Choose one invocation mode; do not run review and scan for the same question.
4. Use --preview to estimate scope and cost before a large scan.
5. Use --format json and --audience agent for machine consumption; reserve text/human output for terminals.
6. Treat OCR comments as evidence inputs, not the final verdict — silently drop Low-confidence noise.
7. Never fabricate or hardcode API keys; stop and ask the user for credentials.
8. Auto-fix only with explicit intent, on safe High/Medium items, and verify before committing.
9. Route human approve/block judgment to code-review, Git cleanup to git-workflow, and live debugging to debugging.

References

• references/intake-and-modes.md
• references/configuration-and-rules.md
• references/cicd-and-plugins.md
• scripts/install.sh
• scripts/run-review.sh
• scripts/run-scan.sh
• OpenCodeReview GitHub Repository
• OpenCodeReview Documentation