OpenCodeReview (OCR)

OpenCodeReview (kurz OCR, CLI-Befehl ocr) ist ein Open-Source-Kommandozeilenwerkzeug, das mit Hilfe eines LLM (z. B. Claude, GPT, DeepSeek, lokale Modelle über Ollama, llama.cpp, …) automatisierte Code-Reviews auf Git-Diffs durchführt. OCR übernimmt die Dateiauswahl, Regelauflösung, Ausschlusslogik, Diff-Verarbeitung und delegiert die eigentliche inhaltliche Bewertung an ein LLM, das über ein Set von Tools (file_read, code_search, code_comment, …) mit dem Code interagiert.

Das Projekt steht unter der Apache-2.0-Lizenz und wird von Alibaba gepflegt: https://github.com/alibaba/open-code-review.

Überblick & Grundkonzept

OCR liest einen Git-Diff (Arbeitsverzeichnis, ein einzelner Commit oder ein Branch-Vergleich), filtert die betroffenen Dateien nach konfigurierbaren Regeln, und startet für jede relevante Datei einen eigenen LLM-Sub-Agenten. Dieser Agent darf Werkzeuge aufrufen, um sich Kontext zu verschaffen (Diff anderer Dateien lesen, im Repo suchen, Datei-Inhalte lesen), und gibt am Ende strukturierte Review-Kommentare über das Tool code_comment aus.

Zentrale Eigenschaften:

Pro Datei ein eigener Kontext.
Es gibt kein Cross-File-Reasoning im eigentlichen Sinn. Jede Datei wird in ihrer eigenen LLM-Konversation bewertet. Kontext aus anderen Dateien dient nur dem Verständnis, nie als Kommentarziel.
LLM-agnostisch.
Anthropic- und OpenAI-kompatible Endpunkte werden nativ unterstützt, ebenso lokale Modelle über Ollama oder beliebige OpenAI-kompatible Gateways.
Deterministische Dateifilterung.
Ein Filter entscheidet nachvollziehbar, welche Dateien überhaupt zum LLM geschickt werden.
Layered Regelsystem.
Vier Prioritätsebenen (CLI-Flag → Projekt → global → eingebauter Systemstandard) bestimmen, worauf sich der Reviewer pro Dateityp konzentriert.
Vollständig lokal & nachvollziehbar.
Jede Review-Session wird als JSONL-Transkript unter ~/.opencodereview/sessions/ gespeichert und kann im integrierten Web-Viewer inspiziert werden.
Delegationsfähig.
Statt eines eigenen LLM-Zugangs kann OCR auch nur als „Scaffolding“ dienen und die eigentliche Review-Logik an einen Host-Agenten (z. B. Claude Code) abgeben (Delegation Mode).

Installation

Es gibt sechs unterstützte Installationswege.

NPM (empfohlen)

npm install -g @alibaba-group/open-code-review

https://www.npmjs.com/package/@alibaba-group/open-code-review

Bestimmte Version anheften: Aktuell „Verison 1.11.5“

npm install -g @alibaba-group/open-code-review@<version>

Automatische Updates.
Bei NPM-Installation hält sich ocr standardmäßig selbst aktuell bei jedem Aufruf prüft der Wrapper im Hintergrund die Registry (Cooldown: 18 Minuten, einstellbar über OCR_UPDATE_INTERVAL) und aktualisiert bei Bedarf automatisch, ohne den laufenden Review zu beeinträchtigen.

Automatische Updates deaktivieren mit:

export OCR_NO_UPDATE=1

Deinstallieren:

npm uninstall -g @alibaba-group/open-code-review

Homebrew (macOS / Linux)

brew install open-code-review
# Upgrade:
brew upgrade open-code-review

MacPorts (macOS)

sudo port install open-code-review
# Upgrade:
sudo port upgrade open-code-review

Installationsskript (curl | sh)

Praktisch für CI-Basisimages und Server ohne Node.js lädt direkt das statische GitHub-Release-Binary inklusive Prüfsummenverifikation:

curl -fsSL https://open-codereview.ai/install.sh | sh

Variable	Standard	Zweck
`OCR_INSTALL_DIR`	`/usr/local/bin`	Zielort für die `ocr`-Binärdatei
`OCR_VERSION`	neuestes Release	Feste Version anheften (z. B. `v1.9.3`)

Unter Windows (PowerShell 5.1+):

irm https://open-codereview.ai/install.ps1 | iex

(analoge Variablen $env:OCR_INSTALL_DIR / $env:OCR_VERSION, Standardpfad %LOCALAPPDATA%\Programs\ocr).

GitHub-Release-Binary direkt

# macOS (Apple Silicon)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# Linux x86_64
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

(analog für darwin-amd64, linux-arm64, windows-amd64.exe, windows-arm64.exe).

Aus dem Quellcode bauen

Voraussetzungen: Go ≥ 1.25, Git, Make.

git clone https://github.com/alibaba/open-code-review.git
cd open-code-review
make build              # schreibt dist/opencodereview
sudo cp dist/opencodereview /usr/local/bin/ocr

Für andere Plattformen: make build-linux-amd64, make build-linux-arm64, make build-darwin-amd64, make build-darwin-arm64, make build-windows-amd64, make build-windows-arm64, oder make build-all für alle sechs auf einmal. Mit make sha256sum wird zusätzlich eine sha256sum.txt erzeugt. Tests laufen über make test (LC_ALL=C go test -v -race -count=1 ./...).

Installation prüfen

ocr version
ocr --help
ocr review --help

Bei „command not found“: which ocr und $PATH prüfen.

Wo OCR seinen Zustand speichert

Pfad	Inhalt
`~/.opencodereview/config.json`	LLM-Endpunkt, Sprache, Telemetrie-Konfiguration
`~/.opencodereview/rule.json`	Optionale globale Review-Regeln
`~/.opencodereview/sessions/<encoded-repo-path>/<session-id>.jsonl`	JSONL-Transkript jeder Review-Session (für `ocr viewer`)
`~/.opencodereview/{last-update-check,update.lock,update-available}`	Zustand der NPM-Wrapper-Updateprüfung
`<repo>/.opencodereview/rule.json`	Optionale projektspezifische Regeln (commit-fähig)

OCR schreibt außer dem NPM-Binary-Download nichts außerhalb von ~/.opencodereview/. Das Verzeichnis löschen genügt für eine saubere Deinstallation.

Schnellstart (QuickStart)

Voraussetzungen: Git ≥ 2.41, Node.js ≥ 18, ein LLM-API-Schlüssel (nicht nötig bei Delegation Mode).

Schritt 1 — CLI installieren

$> npm install -g @alibaba-group/open-code-review

added 2 packages in 19s

$> ocr version

open-code-review v1.9.3 (c35ddd722) windows/amd64
built at: 2026-08-14T03:35:43Z
https://github.com/alibaba/open-code-review

Schritt 2 — LLM konfigurieren

Bei Nutzung von Delegation Mode (z. B. innerhalb von Claude Code) liefert der Host-Agent das Modell — dieser Schritt entfällt dann.

Interaktiv:

ocr config provider

Führt durch die Auswahl eines eingebauten oder benutzerdefinierten Providers, API-Schlüssel-Eingabe, Modellwahl, speichert alles und testet die Verbindung mit ocr llm test. Modell später wechseln:

ocr config model

Nicht-interaktiv (CI / Skripte): Hier am Beispiel einer Konfiguration für Unsloth Studio mit einem unsloth/Qwen3.8-27B-GGUF:Q6_K Modell.

$> config set llm.url http://127.0.0.1:8888/v1
Set llm.url = http://127.0.0.1:8888/v1

$> ocr config set llm.auth_token sk-unsloth-xxx
Set llm.auth_token = sk-u***b4d3

$> ocr config set llm.model unsloth/Qwen3.8-27B-GGUF:Q6_K
Set llm.model = unsloth/Qwen3.8-27B-GGUF:Q6_K

$> ocr config set llm.use_anthropic false
Set llm.use_anthropic = false

Schritt 3 — Verbindung testen

$> ocr llm test

Source: OCR config file
URL:    http://127.0.0.1:8888/v1
Model:  unsloth/Qwen3.8-27B-GGUF:Q6_K
I am open-code-review, a command-line code review assistant developed by Alibaba.
✓ Connection test successful

no valid LLM endpoint configured → Schritt 2 erneut prüfen. 401/403 → Token falsch/abgelaufen.

Schritt 4 — Ersten Review starten

cd pfad/zu/deinem-repo

# Arbeitsbereich-Modus — Staged + Unstaged + Untracked (Standard)
ocr review

# Branch-Vergleich — Änderungen des Feature-Branches seit Abzweigung von main
ocr review --from main --to feature-branch

# Einzelner Commit
ocr review --commit abc123

Vorschau ohne LLM-Kosten:

ocr review --preview              # Arbeitsbereich
ocr review -c abc123 --preview    # Commit

Maschinenlesbare Ausgabe für andere Systeme:

ocr review --format json --audience agent > review.json

Konfiguration

Die Konfigurationsdatei liegt unter ~/.opencodereview/config.json. Das folgende Beispiel zeigt die Konfiguration für ocr mit einem Qwen3.8-27B Modell das in unsloth Studio läuft.

{
    "llm": {
        "url": "http://127.0.0.1:8888/v1",
        "auth_token": "sk-unsloth-xxxx",
        "model": "unsloth/Qwen3.8-27B-GGUF",
        "protocol": "openai",
        "use_anthropic": false
    }
}

Drei Bearbeitungswege:

Interaktives TUI
ocr config provider / ocr config model, geführte Menüs.
Kommandozeile
ocr config set <key> <value>, ideal für Skripte und CI.
Manuelle Bearbeitung
direkte JSON-Bearbeitung (wird beim nächsten ocr config set-Schreibvorgang neu formatiert).

Modell konfigurieren

ocr config provider

Mit ocr config provider kann man den LLM Provider wählen. Man kann zwischen Official, Custom und Manual wählen.

Die drei Reiter am oberen Rand wechselt man mit Tab oder den Pfeiltasten, ausgewählt wird mit Enter, abgebrochen mit Esc.

Ohne konfiguriertes Modell schlägt ocr review fehl. Die einzige Ausnahme ist der Delegation Mode, bei dem der eigene Coding-Agent das Review mit seinem eigenen LLM ausführt.

Custom: eigener Provider

Der Reiter Custom enthält zunächst nur den Eintrag + Add custom provider. Damit legt man einen eigenen, OpenAI- oder Anthropic-kompatiblen Endpunkt an. Sinnvoll für interne Gateways, Proxys, firmeneigene Inferenz-Endpunkte oder Anbieter, die (noch) nicht in der offiziellen Liste stehen.

Ein selbst angelegter Provider wird gespeichert und erscheint bei jedem weiteren Aufruf von ocr config provider in dieser Liste, ist also wiederverwendbar. Das ist der Unterschied zu Manual: Custom legt einen benannten, dauerhaften Eintrag an, Manual überschreibt direkt die aktive LLM-Konfiguration.

Manual: Endpunkt direkt setzen

Manual konfiguriert den LLM-Endpunkt ohne Umweg über ein Preset. Die Ansicht zeigt zusätzlich die aktuell aktive Einstellung an. Das ist der typische Fall für lokal betriebene Modelle. Ein Modell, das über llama.cpp, LM Studio oder Ollama unter einer OpenAI-kompatiblen /v1-Route bereitgestellt wird. Mit Enter startet die Eingabemaske für URL, Token und Modellnamen.

Zu beachten: OCR arbeitet mit Tool-Calling. Lokale Modelle, die das nicht zuverlässig beherrschen, brechen das Review ab oder liefern leere Ergebnisse — der Verbindungstest allein sagt darüber noch nichts aus.

Official: eingebaute Provider

Der Standardreiter zeigt die mitgelieferten Provider-Presets. Endpunkt-URL und Protokoll sind darin bereits hinterlegt, man muss also nur noch den API-Key eintragen.

Folgende Provider sind mit vorkonfigurierter Basis-URL und Protokoll enthalten — es muss nur der API-Schlüssel eingetragen werden. Ist providers.<name>.api_key nicht gesetzt, greift OCR auf die entsprechende Umgebungsvariable zurück.

Name	Protokoll	Basis-URL	API-Key-Umgebungsvariable
`anthropic`	anthropic	`https://api.anthropic.com`	`ANTHROPIC_API_KEY`
`openai`	openai	`https://api.openai.com/v1`	`OPENAI_API_KEY`
`dashscope`	openai	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`DASHSCOPE_API_KEY`
`dashscope-tokenplan`	openai	`https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`	`DASHSCOPE_TOKENPLAN_KEY`
`volcengine`	openai	`https://ark.cn-beijing.volces.com/api/v3`	`ARK_API_KEY`
`deepseek`	openai	`https://api.deepseek.com`	`DEEPSEEK_API_KEY`
`tencent-tokenhub`	openai	`https://tokenhub.tencentmaas.com/v1`	`TENCENT_TOKENHUB_API_KEY`
`hy-tokenplan`	openai	`https://api.lkeap.cloud.tencent.com/plan/v3`	`TENCENT_HUNYUAN_TOKENPLAN_KEY`
`iflytek`	openai	`https://spark-api-open.xf-yun.com/v1`	`SPARK_API_KEY`
`kimi`	openai	`https://api.moonshot.cn/v1`	`MOONSHOT_API_KEY`
`z-ai`	openai	`https://open.bigmodel.cn/api/paas/v4`	`Z_AI_API_KEY`
`mimo`	openai	`https://api.xiaomimimo.com/v1`	`MIMO_API_KEY`
`minimax`	openai	`https://api.minimax.io/v1`	`MINIMAX_GLOBAL_API_KEY`
`minimax-cn`	openai	`https://api.minimaxi.com/v1`	`MINIMAX_API_KEY`
`baidu-qianfan`	openai	`https://qianfan.baidubce.com/v2`	`QIANFAN_API_KEY`
`siliconflow`	openai	`https://api.siliconflow.com/v1`	`SILICONFLOW_GLOBAL_API_KEY`
`siliconflow-cn`	openai	`https://api.siliconflow.cn/v1`	`SILICONFLOW_API_KEY`
`novita`	openai	`https://api.novita.ai/openai`	`NOVITA_API_KEY`

Basis-URL eines eingebauten Providers überschreiben

Jeder eingebaute Provider hat eine feste Basis-URL. Um z. B. ein selbst gehostetes LiteLLM-Gateway zu verwenden, providers.<name>.url setzen:

ocr config set provider                   litellm
ocr config set model                      openai/gpt-5.4
ocr config set providers.litellm.api_key  "$LITELLM_API_KEY"
ocr config set providers.litellm.url      https://gateway.internal:8000/v1

Die gesetzte url hat Vorrang vor der Standard-Basis-URL. Ist sie nicht gesetzt (oder gelöscht), verwendet OCR den Standard.

Benutzerdefinierte Provider

Jeder nicht in der Tabelle gelistete Providername gilt als benutzerdefiniert und benötigt mindestens url und protocol (anthropic, openai oder openai-responses):

ocr config set provider                             my-gateway
ocr config set custom_providers.my-gateway.url      https://gateway.internal.com/v1
ocr config set custom_providers.my-gateway.protocol openai
ocr config set custom_providers.my-gateway.model    llama-3-70b
ocr config set custom_providers.my-gateway.api_key  "$MY_API_KEY"

openai-responses nutzen, wenn ein Modell die OpenAI Responses API (/v1/responses) benötigt:

ocr config set provider                                               openai-responses-gateway
ocr config set custom_providers.openai-responses-gateway.url          https://api.openai.com/v1
ocr config set custom_providers.openai-responses-gateway.protocol     openai-responses
ocr config set custom_providers.openai-responses-gateway.model        gpt-5
ocr config set custom_providers.openai-responses-gateway.api_key      "$OPENAI_API_KEY"

Ein lokales Ollama-Modell ist einfach ein benutzerdefinierter Provider, der auf den lokalen OpenAI-kompatiblen Endpunkt zeigt:

ocr config set provider                          ollama
ocr config set custom_providers.ollama.url       http://127.0.0.1:11434/v1
ocr config set custom_providers.ollama.protocol  openai
ocr config set custom_providers.ollama.model     qwen3:32b
ocr config set custom_providers.ollama.api_key   ollama

Ollama ignoriert den API-Schlüssel, aber benutzerdefinierte Provider verlangen einen nicht-leeren api_key (es gibt keinen Umgebungsvariablen-Fallback) — daher einen Platzhalterwert setzen. Das Modell selbst muss natives Tool-Calling unterstützen — siehe FAQ: „No tool calls parsed“.

Timeouts

Jede LLM-Anfrage hat einen HTTP-Timeout, standardmäßig 300 Sekunden. Drei Stellschrauben, zunehmender Geltungsbereich:

providers.<name>.timeout_sec / custom_providers.<name>.timeout_sec — pro Provider, in Sekunden.
llm.timeout_sec — für die veraltete llm-Sektion, in Sekunden.
Umgebungsvariable OCR_LLM_TIMEOUT — Ganzzahl Sekunden; überschreibt den Konfigurationswert für jeden Auflösungspfad.

timeout_sec wird nicht von ocr config set unterstützt — direkt in ~/.opencodereview/config.json bearbeiten:

{
  "custom_providers": 
  {
    "ollama": { 
      "url": "http://127.0.0.1:11434/v1", 
      "protocol": "openai", 
      "timeout_sec": 900 
    }
  }
}

Zusätzliche Retry-Statuscodes

Manche Provider verwenden untypische 4xx-Codes für vorübergehende Fehler (z. B. 403/400 für Rate-Limiting). retry_codes lässt OCR diese über den bestehenden SDK-Retry-Mechanismus erneut versuchen:

ocr config set llm.retry_codes 403,400
ocr config set custom_providers.my-gateway.retry_codes 403,400

Nur 4xx-Codes sind zulässig. 408, 409 und 429 werden bereits automatisch wiederholt und beim Lesen aus der Konfiguration ignoriert; bei Angabe über ocr config set gibt OCR eine Warnung aus und lässt sie beim Speichern weg. Alle 5xx-Antworten werden bereits automatisch wiederholt und können nicht zu retry_codes hinzugefügt werden.

Prompt-Limit pro Datei

Standardmäßig eine Obergrenze von 58.888 Tokens pro Dateireview. Für Modelle mit größerem Kontextfenster erhöhen:

$> ocr config set max_tokens 262144

Set max_tokens = 262144

Gilt für ocr review und ocr scan. Einmalige Überschreibung ohne dauerhafte Änderung:

$> ocr review --max-tokens 262144

$> ocr scan --max-tokens 262144

Das Flag hat Vorrang vor der gespeicherten Einstellung; ist keines gesetzt, gilt der Template-Standard. Das Limit gilt pro Datei und ist unabhängig vom Ausgabe-Token-Limit des Modells sowie von --max-tokens-budget (Gesamt-Token-Budget eines Laufs). Zurücksetzen mit ocr config unset max_tokens.

Verbindung prüfen

$> ocr llm test

Source: OCR config file
URL:    http://127.0.0.1:8888/v1
Model:  unsloth/Qwen3.8-27B-GGUF:Q6_K
I am open-code-review, a command-line code review assistant developed by Alibaba.
✓ Connection test successful

Bestehende Umgebungsvariablen wiederverwenden

Sind Claude Codes ANTHROPIC_*– oder OCRs eigene OCR_LLM_*-Umgebungsvariablen bereits gesetzt, übernimmt OCR sie automatisch — keine Konfigurationsdatei nötig.

CC-Switch nutzen

Bei Nutzung von CC-Switch mit aktiviertem Routing-Service genügt es, die Provider-url auf den lokalen Proxy zu zeigen:

# Claude (Anthropic-kompatibel)
ocr config set providers.anthropic.url http://127.0.0.1:15721

# Codex / OpenAI-kompatibel
ocr config set providers.<name>.url http://127.0.0.1:15721/v1

api_key kann ein beliebiger Wert sein.

Providerspezifische Felder senden

Manche Provider verlangen nicht-standardisierte Anfragefelder (z. B. Bedrock-artiges thinking). extra_body (wird in jede Anfrage gemergt) sendet sie ohne Quellcode-Änderung:

ocr config set providers.anthropic.extra_body '{"thinking":{"type":"disabled"}}'

Sitzungsaffinität für Prompt-Caching

OCR leitet für jede LLM-Konversation einen Prompt-Cache-Affinitätsschlüssel ab, gebunden an Review-Session und Aufgabentyp (<session-id>-<task-type>-<scope-hash>). Um dies zu nutzen, den Platzhalter {ocr_session_key} in extra_headers oder extra_body einbetten:

# Als OpenAI-Feld (z. B. prompt_cache_key)
ocr config set providers.openai.extra_body '{"prompt_cache_key": "{ocr_session_key}"}'

# Als HTTP-Header (z. B. x-session-affinity)
ocr config set custom_providers.my-gateway.extra_headers "x-session-affinity={ocr_session_key}"

Review-Sprache konfigurieren

language bestimmt die Sprache der Review-Kommentare (Standard: Englisch):

$> ocr config set language Deutsch

Set language = Deutsch

CLI-Referenz

Übersicht

OpenCodeReview - AI-Powered Code Review CLI

Befehle:
  review, r    Code-Review starten
  rules        Review-Regeln prüfen und debuggen
  config       Konfiguration verwalten
  llm          LLM-Hilfsbefehle
  viewer       Web-UI für die Sitzungsansicht starten
  session, sessions  Gespeicherte Review-Sessions auflisten und untersuchen
  version      Versionsinformationen anzeigen

Befehl	Alias	Funktion
`ocr review`	`ocr r`	Code-Review durchführen und Kommentare ausgeben
`ocr scan`	`ocr s`	Vollständige Dateien scannen, ohne Git-Diff nötig
`ocr rules check <file>`	—	Zeigen, welche Regel für einen Dateipfad gilt und woher sie stammt
`ocr config set <key> <value>`	—	Konfigurationswert dauerhaft speichern
`ocr config unset custom_providers.<name>`	—	Benutzerdefinierten Provider löschen
`ocr config provider`	—	Interaktives Provider-Setup
`ocr config model`	—	Interaktive Modellauswahl
`ocr llm test`	—	Konfigurierten Endpunkt testen
`ocr llm providers`	—	Alle eingebauten Provider auflisten
`ocr session list`	`ocr sessions list`, `ocr session ls`	Gespeicherte Sessions auflisten
`ocr session show <id>`	`ocr sessions show <id>`	Eine Session mit ihren Checkpoints untersuchen
`ocr session comments <id>`	`ocr sessions comments <id>`	Kommentare einer Session ausgeben
`ocr viewer`	—	Lokale Web-UI starten (`localhost:5483`)
`ocr version`	—	Version, Commit, Plattform, Build-Datum, GitHub-URL

`ocr review`

Der Hauptbefehl. Löst einen Git-Diff auf, startet Pro-Datei-Sub-Agenten, sammelt Kommentare und gibt sie aus. Ohne Flags: Arbeitsbereich-Modus (Staged + Unstaged + Untracked im aktuellen Repo).

Flags

Flag	Kurz	Standard	Beschreibung
`--repo <path>`	—	aktuelles Verzeichnis	Git-Repository-Wurzel
`--from <ref>`	—	—	Ausgangs-Ref für den Diff
`--to <ref>`	—	—	Ziel-Ref; berechnet `merge-base(from, to)..to`
`--commit <sha>`	`-c`	—	Einzelnen Commit reviewen (gegen sein Elternobjekt)
`--preview`	`-p`	`false`	Nur Filterpipeline ausführen, kein LLM-Aufruf
`--no-filter`	—	`false`	Alle Kommentare behalten, `REVIEW_FILTER_TASK`-Nachbearbeitung überspringen
`--resume <session-id>`	—	—	Von einer kompatiblen früheren Session fortsetzen
`--format <fmt>`	`-f`	`text`	`text`, `json` oder `sarif` (SARIF 2.1.0 für GitHub Code Scanning)
`--audience <who>`	—	`human`	`human` (Fortschrittsanzeige) oder `agent` (nur Endergebnis/JSON)
`--background <text>`	`-b`	—	Zusätzlicher Anforderungs-/Geschäftskontext
`--concurrency <n>`	—	`8`	Maximale Anzahl parallel geprüfter Dateien
`--timeout <minutes>`	—	`10`	Frist pro Datei (`0` deaktiviert)
`--rule <path>`	—	—	Pfad zu einer benutzerdefinierten Regel-JSON
`--max-tools <n>`	—	Template-Standard	Maximale Tool-Aufruf-Runden pro Datei (`0`=30; 1–9 werden auf 10 angehoben)
`--max-tokens <n>`	—	Konfiguration/Template	Prompt-Token-Obergrenze pro Datei für diesen Lauf
`--provider <name>`	—	—	Konfigurierten Provider für diesen Lauf wählen
`--model <name>`	—	—	Aufgelöstes LLM-Modell für diesen Lauf überschreiben
`--max-git-procs <n>`	—	`16`	Maximale parallele Git-Subprozesse
`--tools <path>`	—	eingebaut	Benutzerdefinierte Tool-Konfigurationsdatei

Modus-Flags schließen sich gegenseitig aus: entweder --from/--to, oder --commit, oder keines (Arbeitsbereich-Modus). Kombinieren ist ein Fehler. --resume unterstützt nur Range- oder Commit-Reviews und ist nicht mit --preview kombinierbar.

Modelwahl pro Lauf

ocr review --provider anthropic --model claude-opus-4-6 --format json
ocr scan --provider openai --model gpt-5.4 --format json

Ein explizites --provider wählt einen gespeicherten Eintrag vor der normalen Quellenauflösung. Ohne --provider gilt die klassische Reihenfolge: gespeicherte Konfiguration → vollständige OCR_LLM_*-Umgebung → vollständige Claude-Code-Umgebung → Shell-rc-Dateien. --model überschreibt nur das Modell innerhalb der gewonnenen Quelle.

Modi

Arbeitsbereich-Modus (Standard)

ocr review

Kombiniert git diff HEAD (bzw. Fallback git diff --staged, falls leer) mit untracked Dateien aus git ls-files --others --exclude-standard, die als vollständige Neuanlagen behandelt werden.

Range-Modus

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

Berechnet merge-base(main, feature-branch)..feature-branch, sodass nur die vom Feature-Branch eingebrachten Änderungen sichtbar sind.

Commit-Modus

ocr review --commit abc123
ocr review -c abc123

Reviewt den Diff von git show abc123.

Unterbrochene Reviews fortsetzen

Jeder Lauf wird als Session-Log unter ~/.opencodereview/sessions/ gespeichert. Die Textausgabe zeigt die Session-ID nicht standardmäßig — dafür ocr session list/show oder --format json (Feld session_id) verwenden:

ocr session list
ocr session show <session-id>
ocr session comments <session-id>
ocr review --from main --to feature-branch --resume <session-id>
ocr review --commit abc123 --resume <session-id>

--resume ist strikt: Arbeitsbereich-Reviews sind nicht fortsetzbar, der Modus muss übereinstimmen, die aufgelösten Refs müssen zum selben Diff führen, ein Provider-/Modellwechsel muss explizit über --provider/--model angefordert werden, und --preview + --resume sind nicht kombinierbar. Ein abgelehntes Fortsetzen schreibt nichts (keine Session, kein LLM-Aufruf).

Ausgabeformate

Text (Standard, --audience human) — Fortschrittszeilen live, danach ein Block pro Kommentar mit Pfad, Zeilenbereich, umbrochenem Kommentartext und ggf. farbigem Diff. Abschließende Zusammenfassung mit Dateizahl, Kommentarzahl, Token-Verbrauch und Laufzeit.

Text (Agent, --audience agent) — identische Kommentare, aber ohne Fortschrittszeilen (geeignet für CI / Weiterverarbeitung durch andere Agenten).

JSON

ocr review --format json --audience agent

{
  "status": "success",
  "llm": { "provider": "anthropic", "model": "claude-opus-4-6" },
  "summary": {
    "files_reviewed": 9,
    "comments": 1,
    "total_tokens": 21344,
    "input_tokens": 18012,
    "output_tokens": 3332,
    "elapsed": "1m12s"
  },
  "comments": [
    {
      "path": "src/foo.go",
      "content": "Nebenläufiger Map-Zugriff ohne Lock — mit sync.RWMutex absichern.",
      "start_line": 42,
      "end_line": 47,
      "existing_code": "m[k] = v",
      "suggestion_code": "mu.Lock(); defer mu.Unlock(); m[k] = v",
      "thinking": "Beim Blick auf Zeile 42 fällt auf, dass die Map …"
    }
  ]
}

Feld	Bedeutung
`status`	`success`, `completed_with_warnings`, `completed_with_errors` oder `skipped`
`llm`	Aufgelöste LLM-Identität (`model` immer vorhanden, `provider` nur bei benanntem Provider)
`message`	Optional, menschenlesbare Zusammenfassung
`summary`	Aggregate des Laufs (fehlt bei `skipped`)
`comments`	Immer vorhanden, ggf. leer
`warnings`	Optional — bei fehlgeschlagenen Sub-Agenten
`session_id`	Optional — für `--resume`
`resume`	Optional — bei fortgesetzten Läufen

Bei keinen relevanten Dateien liefert der JSON-Modus eine skipped-Hülle statt eines leeren Kommentarfelds, damit „nichts zu reviewen“ von „keine Befunde“ unterscheidbar bleibt.

Exit-Codes

Code	Bedeutung
`0`	Review abgeschlossen (ggf. mit Warnungen, ggf. ohne Kommentare)
`1`	Fataler Fehler — z. B. LLM-Endpunkt nicht auflösbar, alle Sub-Agenten fehlgeschlagen

`ocr scan`

Vollständiger Datei-Review ohne Git-Diff — nützlich zum Audit eines unbekannten Codebestands oder eines Verzeichnisses ohne aussagekräftigen Diff.

ocr scan --preview                              # Vorschau ohne LLM-Aufruf
ocr scan --path internal/agent                  # ein Verzeichnis
ocr scan --path internal/agent,internal/llm/client.go
ocr scan --exclude '**/generated/*,*.pb.go'

Flag	Kurz	Standard	Beschreibung
`--path <list>`	—	ganzes Repo	Kommagetrennte Pfade/Verzeichnisse
`--exclude <patterns>`	—	—	Kommagetrennte gitignore-artige Ausschlussmuster
`--preview`	`-p`	`false`	Dateien nur auflisten/filtern, kein LLM-Aufruf

`ocr session`

ocr session list [--limit 50] [--json]
ocr session show [--json] <session-id>
ocr session comments [--json] [--severity high] [--category bug,security] <session-id>

Flag	Standard	Beschreibung
`--repo <path>`	aktuelles Verzeichnis	Betroffenes Repository
`--json`	`false`	Ausgabe als JSON
`--limit <n>` (nur `list`)	`20`	Maximalzahl der Sessions (`0` = unbegrenzt)
`--severity <list>` (nur `comments`)	alle	`critical`, `high`, `medium`, `low`
`--category <list>` (nur `comments`)	alle	z. B. `bug`, `security`

`ocr rules check`

ocr rules check [--repo <path>] [--rule <path>] <file-path>

Zeigt Quellschicht, passendes Glob-Muster und den aufgelösten Regeltext für eine Datei.

$ ocr rules check src/main/java/com/example/Foo.java
File: src/main/java/com/example/Foo.java
Source: System built-in
Pattern: **/*.java
Rule:
────────────────────────────────────────
<Inhalt von java.md>
────────────────────────────────────────

`ocr config`

ocr config set <key> <value>
ocr config unset custom_providers.<name>
ocr config provider
ocr config model

Siehe Konfiguration für den vollständigen Schlüsselkatalog.

`ocr llm`

ocr llm test — löst den Endpunkt exakt wie ocr review auf, sendet eine Test-Konversation und gibt Quelle, URL, Modell und die Modellantwort aus.

ocr llm providers — listet alle eingebauten Provider in einer Dreispaltentabelle (Name, Protokoll, Basis-URL).

`ocr viewer`

ocr viewer                       # Standardport localhost:5483
ocr viewer --addr :3000          # auf allen Interfaces, Port 3000
ocr viewer --addr 0.0.0.0:8080   # alle Interfaces

Siehe Session Viewer.

`ocr completion`

# Bash — einmalig
source <(ocr completion bash)
# Bash — dauerhaft (Linux)
ocr completion bash > /etc/bash_completion.d/ocr
# Bash — dauerhaft (macOS)
ocr completion bash > $(brew --prefix)/etc/bash_completion.d/ocr

# Zsh — dauerhaft
ocr completion zsh > "${fpath[1]}/_ocr"

# Fish — einmalig
ocr completion fish | source
# Fish — dauerhaft
ocr completion fish > ~/.config/fish/completions/ocr.fish

# PowerShell — einmalig
ocr completion powershell | Out-String | Invoke-Expression
# PowerShell — dauerhaft: Skript erzeugen und im Profil per Dot-Sourcing einbinden
ocr completion powershell > ocr.ps1

`ocr version`

ocr version
ocr --version
ocr -V

Tipps & Fallstricke

--audience agent impliziert nicht --format json — beides steuert unterschiedliche Dinge (ruhige UI vs. strukturierte Ausgabe); bei Bedarf kombinieren.
--background ist eines der wirksamsten Flags für die Review-Qualität — Anforderungs-/PR-Text immer mitgeben, wenn OCR von einem anderen Agenten aus aufgerufen wird.
Eine Datei, deren Diff allein 80 % von MAX_TOKENS (Standard 58888) übersteigt, wird vor dem LLM-Aufruf verworfen — geloggt, aber nicht laufabbrechend.
Die Planungsphase wird automatisch übersprungen, wenn die geänderten Zeilen einer Datei unter PLAN_MODE_LINE_THRESHOLD (50) liegen.

Die eingebauten Tools

OCR liefert sechs eingebaute Tools, die das LLM während eines Reviews aufrufen kann.

Verfügbarkeit pro Phase

Tool	Plan	Haupt	Zweck
`task_done`	✗	✓	„Ich bin fertig“ signalisieren — beendet die Schleife
`code_comment`	✗	✓	Review-Kommentar mit Zeilenbereich + Vorschlag ausgeben
`file_read`	✗	✓	Ausschnitt einer Datei im Nach-Änderungs-Zustand lesen
`file_read_diff`	✓	✓	Diff einer anderen Datei lesen (Cross-File-Kontext)
`file_find`	✓	✓	Dateien nach Dateinamens-Stichwort finden
`code_search`	✓	✓	Repo-weite Suche (Literal oder Regex)

Kontext-Tools sind nur lesbarer Kontext, keine Kommentarziele. Der main_task-Prompt verbietet ausdrücklich Kommentare zu Befunden in anderen Dateien. file_read, file_read_diff, file_find und code_search dienen nur dem besseren Verständnis der aktuellen Datei.

Mit --tools <path> lässt sich die Tool-Registry überschreiben (Tool deaktivieren, Beschreibung ändern, neues Tool auf Basis eines bestehenden Providers hinzufügen).

`task_done`

{ "name": "task_done", "input": { "state": "DONE" } }

state ist DONE (Standard) oder FAILED (fast nie die richtige Wahl). Wird sofort verarbeitet (vor der Session-Log-Speicherung) — der state-Wert beeinflusst weder Exit-Codes noch wird er persistiert.

`code_comment`

{
  "name": "code_comment",
  "input": {
    "path": "optional — Dateipfad-Override",
    "comments": [
      {
        "content": "Kommentartext in der konfigurierten Sprache",
        "existing_code": "Ausschnitt aus dem Diff zur Verankerung",
        "suggestion_code": "optionaler Fix-Ausschnitt",
        "thinking": "optional — Begründung des Modells"
      }
    ]
  }
}

comments ist ein Array — mehrere Kommentare pro Aufruf möglich. content und existing_code sind Pflichtfelder; suggestion_code optional, aber erwünscht. path wird meist automatisch von OCR eingefügt. thinking ist ein Laufzeit-only-Feld — nicht im an das Modell kommunizierten Schema, wird aber gespeichert, falls das Modell es trotzdem liefert.

Verankerungsalgorithmus — OCR sucht existing_code per dynamischem Sliding-Window im Diff:

Hunk-Neuseite (Kontext + hinzugefügte Zeilen) → neue Zeilennummern. Bei Fehlschlag: Hunk-Altseite (Kontext + gelöschte Zeilen) → alte Zeilennummern.
Voller Neu-Datei-Scan — falls kein Hunk-Match, wird die komplette Nach-Änderungs-Datei zeilenweise durchsucht.
Re-Location-Task — bei anhaltendem Fehlschlag auf nicht-trivialen Diffs bittet OCR das Modell erneut um Verankerung.

Der Vergleich ist whitespace-unempfindlich. Als letzter Ausweg wird der Kommentar mit start_line=0 ausgeliefert — das signalisiert: „das Problem ist real, aber die genaue Stelle muss manuell gesucht werden“.

`file_read`

{ "name": "file_read", "input": { "file_path": "src/foo.go", "start_line": 10, "end_line": 80 } }

Feld	Pflicht	Standard	Hinweis
`file_path`	ja	—	relativ zur Repo-Wurzel
`start_line`	nein	`1`	1-indexiert
`end_line`	nein	Dateiende	inklusiv

Ausgabe: jede Inhaltszeile mit vorangestellter Zeilennummer und |-Trenner. Limit: 500 Zeilen pro Aufruf — größere Bereiche werden abgeschnitten (IS_TRUNCATED: true). Liest nur die geänderte Version — für die alte Version dient file_read_diff.

`file_read_diff`

{ "name": "file_read_diff", "input": { "path_array": ["src/api/handler.go", "src/db/queries.go"] } }

Liest den Diff einer oder mehrerer anderer Dateien im selben Änderungssatz. Nicht enthaltene Pfade werden stillschweigend übersprungen; sind alle angefragten Pfade nicht im Änderungssatz, liefert das Tool Error: diff not found for the requested paths.

`file_find`

{ "name": "file_find", "input": { "query_name": "UserService", "case_sensitive": false } }

Sucht Dateien nach Substring im Dateinamen (nicht im vollen Pfad). Bis zu 100 Treffer; darüber hinaus stillschweigend abgeschnitten (dann code_search verwenden). Kandidaten stammen aus git ls-files (Arbeitsbereich) bzw. git ls-tree (Range/Commit). Erweiterungslose Dateien werden übersprungen — außer Makefile, Dockerfile, LICENSE, Vagrantfile, Containerfile.

`code_search`

{
  "name": "code_search",
  "input": {
    "search_text": "TODO|FIXME",
    "file_patterns": ["*.go", ":(exclude)vendor/"],
    "case_sensitive": false,
    "use_perl_regexp": true
  }
}

Basiert auf git grep, versteht Pathspec-Syntax und beachtet .gitignore. Ergebnisse sind nach Datei gruppiert. Limit: 100 Treffer pro Datei. Leerer search_text liefert einen Fehler statt jede Zeile zu matchen.

Tools anpassen

Tool deaktivieren: tools.json kopieren, gewünschten Eintrag entfernen, dann ocr review --tools ./my-tools.json. Für einen „nur-Kommentar“-Reviewer beispielsweise nur code_comment und task_done behalten.

Tool umbeschreiben: name beibehalten (Provider werden intern über den Namen aufgelöst), description anpassen, um das Modell zu steuern.

Neue Tool-Namen erfordern Go-seitige Verdrahtung (internal/tool/definitions.go).

Review-Regeln (Rules)

Regeln bestimmen, worauf OCR pro Datei achtet. Sie liegen in JSON-Dateien auf drei Ebenen plus einem eingebauten Systemstandard.

Prioritätskette

Priorität	Quelle	Pfad	Anmerkung
1 (höchste)	`--rule`-Flag	benutzerdefiniert	CLI-Override, gewinnt immer
2	Projekt-Konfiguration	`<repoDir>/.opencodereview/rule.json`	commit-fähig
3	Globale Konfiguration	`~/.opencodereview/rule.json`	nutzerweite Präferenzen
4 (niedrigste)	Systemstandard	eingebettete `system_rules.json`	deckt gängige Sprachen ab

Fehlt eine höher priorisierte Datei, wird sie stillschweigend übersprungen (kein Fehler) — die Systemebene ist immer vorhanden.

Regeldatei-Format (Ebenen 1–3)

{
  "include": ["src/**/*.{ts,tsx}", "src/**/*.go"],
  "exclude": ["**/*.test.ts", "**/generated/**"],
  "rules": [
    {
      "path": "src/api/**/*.go",
      "rule": "Alle exportierten Handler müssen Anfragen validieren, bevor sie verwendet werden."
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "SQL auf Injection-Risiken, Parameterfehler und fehlende schließende Tags prüfen."
    }
  ]
}

include — optional. Glob-Muster, die eingebaute Standard-Ausschlussmuster (v. a. Testdateien) umgehen. Keine Whitelist — nicht passende Dateien durchlaufen weiterhin die restlichen Gates.
exclude — optional. Muster für Dateien, die OCR nicht reviewen soll. Höchste Priorität im Filter.
rules — Array aus {path, rule}, in Deklarationsreihenfolge ausgewertet. Der erste passende path bestimmt den Prompt.

Regelauflösung pro Datei

--rule (benutzerdefiniert) in Deklarationsreihenfolge.
<repo>/.opencodereview/rule.json in Deklarationsreihenfolge.
~/.opencodereview/rule.json in Deklarationsreihenfolge.
Eingebettete System-Regelschicht als Fallback.

Auszug der eingebetteten system_rules.json-Muster (relative Reihenfolge):

Muster	Regeldokument
`*/.properties`	`properties.md` — i18n/Konfigurationsdateien
`*/{mapper,dao}*.xml`	`mapper_dao_xml.md` — MyBatis-artige Mapper-SQL
`**/pom.xml`	`pom_xml.md` — Maven-Abhängigkeiten
`**/build.gradle`	`build_gradle.md` — Gradle-Abhängigkeiten
`**/package.json`	`package_json.md` — NPM-Abhängigkeiten/Skripte
`**/Cargo.toml`	`cargo_toml.md` — Rust-Manifest
`**/composer.json`	`composer_json.md` — Composer-Abhängigkeiten
`*/.{json,json5}`	`json.md`
`.github/workflows/*/.{yaml,yml}`	`github_workflows.md`
`.github/*/.{yaml,yml}`	`github_config.md`
`*/.{yaml,yml}`	`yaml.md`
`*/.java`	`java.md`
`*/.go`	`go.md`
`*/.{ftl,ftlh,ftlx}`	`freemarker.md`
`*/.ets`	`arkts.md` — ArkTS/HarmonyOS
`*/.astro`	`astro.md`
`*/.{ts,js,tsx,jsx}`	`ts_js_tsx_jsx.md`
`*/.{kt}`	`kotlin.md`
`*/.rs`	`rust.md`
`*/.{cpp,cc,hpp}`	`cpp.md`
`*/.c`	`c.md`
`*/.py`	`python.md`
`*/.{php,phtml}`	`php.md`
`*/.proto`	`protobuf.md`
`*/.po` / `*/.pot`	`po.md` / `pot.md`
`*/.{graphql,gql}`	`graphql.md`
`*/.prisma`	`prisma.md`
`*/.jl`	`julia.md`
`*/.{tf,hcl,tfvars}`	`terraform.md`
`*/.bicep`	`bicep.md`
(Fallback)	`default.md`

`ocr rules check` — welche Regel gewinnt

ocr rules check src/main/java/com/example/UserService.java
ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml

Zeigt Quellschicht und Muster — ideal zum Debuggen „warum feuert meine Regel nicht?“.

Rezepte

Projektebene: Coding-Standard erzwingen (<repo>/.opencodereview/rule.json, commit-fähig):

{
  "rules": [
    { "path": "src/api/**/*.go", "rule": "Jeder öffentliche Handler muss `defer tx.Rollback()` direkt nach Transaktionsbeginn aufrufen." },
    { "path": "**/*mapper*.xml", "rule": "SQL auf Injection-Risiken, fehlende Parameterbindung und offene XML-Tags prüfen." }
  ]
}

Projektebene: generierten Code überspringen, nur src fokussieren:

{
  "include": ["src/**/*.{ts,tsx,js,jsx}"],
  "exclude": ["**/*.gen.ts", "**/generated/**"]
}

Pro-PR-Override:

ocr review --rule ./.review-rules-only-for-this-pr.json

Globale persönliche Präferenzen (~/.opencodereview/rule.json):

{
  "rules": [
    { "path": "**/*.{ts,tsx,js,jsx}", "rule": "Immer auf unbehandelte Promise-Rejections prüfen; bei `// eslint-disable` ohne Begründung warnen." }
  ]
}

MCP-Server als Werkzeugquelle

OCR kann als Model-Context-Protocol-(MCP)-Client agieren. Man verweist auf einen oder mehrere externe MCP-Server, und deren Tools stehen dem Review-Agenten zusätzlich zu den eingebauten Tools zur Verfügung.

Wann sinnvoll

Ticket-/Issue-Abgleich — verknüpftes Jira-/GitHub-Issue abrufen, um zu prüfen, ob die Änderung der Anforderung entspricht.
Docs / Wissensdatenbank — interne API-Dokumentation oder Coding-Standards, damit Kommentare auf die echten Hausregeln verweisen.
Individuelle Analyse — Linter, Schema-Validator, Abhängigkeits-Checker als Bedarfstool.

Reicht ein reines Lesen des Repos, decken die eingebauten Tools das bereits ab — MCP ist für Kontext außerhalb des Checkouts gedacht.

Konfiguration

# Minimal: nur ein Befehl
ocr config set mcp_servers.docs.command npx

# Argumente
ocr config set mcp_servers.docs.args '["-y", "@acme/docs-mcp-server"]'

# Freigegebene Tools einschränken
ocr config set mcp_servers.docs.tools '["search_docs", "get_page"]'

# Setup-Befehl vor Serverstart
ocr config set mcp_servers.docs.setup "npm install -g @acme/docs-mcp-server"

# Umgebungsvariablen
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'

Entfernen:

ocr config unset mcp_servers.docs

Feld	Typ	Pflicht	Beschreibung
`command`	string	✓	Ausführbare Datei, die den Server startet
`args`	string[]		Argumente für `command`
`tools`	string[]		Allowlist der zu registrierenden Tools (leer = alle)
`setup`	string		Einmaliger Shell-Befehl vor Serverstart (5-Minuten-Timeout, läuft in der Repo-Wurzel)
`env`	string[]		Zusätzliche `KEY=VALUE`-Umgebungsvariablen

Namenskonflikte

MCP-Tool-Namen teilen sich einen Namensraum mit den eingebauten Tools. Kollidiert ein Servertool mit einem eingebauten/reservierten Namen (file_read, code_search, task_done, …) oder einem bereits registrierten anderen Server-Tool, wird es übersprungen und eine Warnung geloggt. Die erste Registrierung gewinnt.

Fehlerdiagnose

Alle MCP-Diagnosen gehen an stderr (Präfix [ocr]), niemals nach stdout:

Running setup for MCP server "x": …
failed to start MCP server "x": … — Subprozess verband nicht innerhalb 30 Sekunden, oder command ist nicht auf PATH.
tool "y" conflicts with built-in tool, skipping
allowed tool "y" not found in server's tool list — Tippfehler in tools prüfen.

Session Viewer (Web-UI)

ocr viewer ist ein kleiner, in die Binärdatei eingebetteter HTTP-Server, der vergangene Review-Sessions browserfreundlich darstellt — ohne externe Abhängigkeiten, direkt aus den JSONL-Dateien auf der Platte.

Starten

ocr viewer                       # localhost:5483
ocr viewer --addr :3000          # alle Interfaces, Port 3000
ocr viewer --addr 0.0.0.0:8080   # alle Interfaces

Standardadresse localhost:5483. Der Server hält den Vordergrund (Strg+C beendet ihn). Sessions werden bei jeder Anfrage neu aus ~/.opencodereview/sessions/ gelesen — ein laufender Review in einem anderen Terminal erscheint sofort nach Erzeugung seiner JSONL-Datei.

DNS-Rebinding-Schutz. Der Viewer prüft den Host-Header gegen eine Loopback-Allowlist (localhost, 127.0.0.1, ::1). Ein konkreter Bind-Host wird automatisch hinzugefügt, aber Wildcard-Binds (:3000, 0.0.0.0, ::) nicht — Zugriff über eine LAN-IP liefert dann forbidden host. Für Wildcard-Zugriff OCR_VIEWER_ALLOWED_HOSTS mit kommagetrennter Hostliste setzen (z. B. OCR_VIEWER_ALLOWED_HOSTS=box.local,192.168.1.10).

Drei Seiten (Full Scan)

/ Liste aller Repositories mit Sessions

/r/{repo} Sessionliste für ein Repo, neueste zuerst

/r/{repo}/{sessionID} Volles Detail einer Session

Session-Detail

Der Session-Detail-Screen ist die Detailansicht des Session Viewers. Er zeigt alles, was während einer einzelnen Review-Ausführung passiert ist: unter welchen Rahmenbedingungen sie lief, welche Dateien tatsächlich geprüft wurden, wie viele Tokens das gekostet hat, welche Befunde entstanden sind und wie der Agent zu diesen Befunden gekommen ist.

Man erreicht den Screen aus der Session-Liste, indem man eine Session auswählt.

Grundkonzept: Was ist eine Session?

Eine Session ist eine einzelne Ausführung eines Reviews — also das, was ein Aufruf von ocr review bzw. ocr scan erzeugt. Jede Session wird lokal persistiert und bekommt eine eindeutige Session-ID. Diese ID ist gleichzeitig der Wiederaufnahme-Schlüssel: Eine abgebrochene Session lässt sich mit --resume <session-id> fortsetzen.

Der Session Viewer liest diese gespeicherten Daten und stellt sie dar. Er ist eine reine Leseansicht:

Es wird kein Review neu ausgeführt und kein LLM aufgerufen.
Es werden keine Kommentare geändert, aufgelöst oder gepostet.
Alle Daten stammen aus dem lokalen Session-Verzeichnis.

Der Screen beantwortet damit drei Arten von Fragen:

Frage	Relevanter Abschnitt
Wurde vollständig und korrekt geprüft?	Session-Header, Coverage, Files Reviewed
Was hat das gekostet?	Token Usage
Was wurde gefunden — und warum?	Review Comments, Conversations

Aufbau des Screens

Der Screen ist als vertikale Abfolge eigenständiger Karten aufgebaut. Von oben nach unten:

Kopfzeile mit Breadcrumb-Navigation
Session-Header — Metadaten der Ausführung
Coverage — Abdeckung der Dateiauswahl
Token Usage — Verbrauch und Anzahl der LLM-Aufrufe
Review Comments — die Befunde, filterbar und nach Datei gruppiert
Files Reviewed — alle geprüften Dateien, auch die ohne Befund
Conversations — der Gesprächsverlauf des Agents je Datei

Die Reihenfolge folgt bewusst dem Vertrauensaufbau: erst Rahmen, dann Vollständigkeit, dann Ergebnis, zuletzt Nachvollziehbarkeit. Karten mit einem Pfeilsymbol (›) sind zusammengeklappt und lassen sich per Klick öffnen; die Zahl am rechten Rand zeigt vorab, wie viel Inhalt dahinter steckt.

Kopfzeile

Die Kopfzeile enthält den Breadcrumb-Pfad Open Code Review Viewer / <Projekt> / <Session-ID>.

Der Projektname ist ein Link zurück zur Session-Liste dieses Projekts. Die Session-ID wird gekürzt dargestellt, weil UUIDs die Kopfzeile sonst dominieren würden — die vollständige ID steht im Session-Header darunter.

Session-Header

Der Header beschreibt den Rahmen, unter dem das Review lief. Diese Angaben sind die Voraussetzung dafür, Ergebnisse überhaupt einordnen zu können: Dieselbe Codebasis liefert mit einem anderen Modell oder einem anderen Diff-Bereich andere Befunde.

Feld	Bedeutung
`Session`	Vollständige Session-ID. Wird für `--resume` und zum Melden von Problemen benötigt.
`CWD`	Arbeitsverzeichnis, in dem der Review-Aufruf ausgeführt wurde.
`BRANCH`	Aktiver Git-Branch zum Zeitpunkt der Ausführung.
`MODE`	Der Review-Modus, siehe unten.
`COMMIT`	Referenz auf den geprüften Stand. Je nach Modus der geprüfte Commit oder der HEAD-Stand des Arbeitsverzeichnisses.
`MODEL`	Das konkret verwendete Modell, inklusive Provider- bzw. Quantisierungs-Kennung.
`DURATION`	Reine Laufzeit des Reviews.
`FILES`	Anzahl der Dateien, die für das Review ausgewählt wurden.
`STATUS`	Endzustand der Session.

Review-Modi

Der Modus bestimmt, woher die zu prüfenden Änderungen stammen:

workspace — alle Änderungen im Arbeitsverzeichnis (staged, unstaged, untracked).
range — die Änderungen eines Branches gegenüber seinem Abzweigpunkt (--from / --to, Merge-Base).
commit — genau ein Commit (--commit <sha>).
scan — vollständige Dateien statt eines Diffs (ocr scan); nützlich für Audits von fremdem Code oder Verzeichnissen ohne aussagekräftige Historie.

Status

complete — Das Review ist regulär durchgelaufen.
running — Die Session läuft noch; die Kennzahlen sind vorläufig.
interrupted — Die Ausführung wurde abgebrochen und kann per --resume fortgesetzt werden.
failed — Die Session wurde durch einen Fehler beendet.

Bei allem außer complete sind Coverage- und Finding-Zahlen als Zwischenstand zu lesen, nicht als Aussage über die Qualität der Änderung.

Coverage

Coverage beantwortet die Frage, ob wirklich alles Relevante geprüft wurde. Der Hintergrund: Die Dateiauswahl in Open Code Review ist ein deterministischer Schritt und keine Modellentscheidung. Genau deshalb lässt sie sich als harte Zahl anzeigen — und genau deshalb ist diese Zahl belastbar.

Die Karte zeigt fünf Zähler:

Zähler	Bedeutung
Selected	Dateien, die die Auswahl- und Filterlogik als reviewrelevant bestimmt hat. Die Bezugsgröße für alles Weitere.
Completed	Dateien, die in dieser Session vollständig geprüft wurden.
Reused	Dateien, deren Ergebnis aus einer früheren Session übernommen wurde, weil sich der Inhalt nicht geändert hat. Typisch bei `--resume` und bei wiederholten Reviews desselben Stands — spart Zeit und Tokens.
Failed	Dateien, deren Prüfung fehlgeschlagen ist, etwa durch Timeouts, Provider-Fehler oder Kontextüberläufe.
Waived	Dateien, die bewusst übersprungen wurden, z. B. durch Ausschlussregeln, Größenlimits oder als generiert erkannte Artefakte.

Lesehilfe: Selected sollte der Summe der übrigen vier Zähler entsprechen. Weicht das ab, läuft die Session noch oder wurde abgebrochen.

Ein Wert größer null bei Failed ist das wichtigste Warnsignal des Screens: Für diese Dateien liegt kein Ergebnis vor, und das Fehlen von Befunden bedeutet dort ausdrücklich nicht „keine Probleme gefunden“. Ein hoher Waived-Wert ist dagegen meist unkritisch, lohnt aber einen Blick in die Filterkonfiguration — er kann auch bedeuten, dass eine Ausschlussregel zu breit greift.

Token Usage

Diese Karte macht die Kosten der Session transparent.

Kennzahl	Bedeutung
Prompt Tokens	An das Modell gesendete Tokens: Regeln, Diffs, Dateiinhalte, Tool-Ergebnisse.
Completion Tokens	Vom Modell erzeugte Tokens: Befunde, Zwischenüberlegungen, Tool-Aufrufe.
Total Tokens	Summe beider Werte — die relevante Größe für Abrechnung und Vergleich.
LLM Requests	Anzahl der einzelnen Modellaufrufe in dieser Session.

Zwei Beobachtungen sind normal und erklären das übliche Zahlenbild:

Prompt-Tokens dominieren deutlich. Ein Review liest sehr viel Kontext und schreibt vergleichsweise wenig Text. Ein Verhältnis von vielen Prompt- zu wenigen Completion-Tokens ist der Regelfall, kein Fehler.
Es gibt mehr Requests als Dateien. Dateien werden zu Review-Einheiten gebündelt, die als Sub-Agents mit eigenem Kontext laufen; hinzu kommen Tool-Aufrufe sowie die separaten Schritte zur Positionierung und Reflexion der Kommentare. Jeder dieser Schritte ist ein eigener Aufruf.

File breakdown

Hinter File breakdown liegt die Aufschlüsselung des Verbrauchs pro Datei. Damit lassen sich Ausreißer identifizieren — einzelne große oder stark verzweigte Dateien verursachen häufig einen überproportionalen Anteil der Gesamtkosten. Das ist der übliche Startpunkt, wenn Reviews im CI zu teuer oder zu langsam werden.

Review Comments

Die zentrale Karte des Screens. Die Überschrift nennt die Gesamtzahl der Befunde (findings) der Session.

Filter

Zwei unabhängige Filterleisten schränken die Liste ein. Jede Schaltfläche zeigt die Anzahl der Befunde in dieser Ausprägung, sodass die Verteilung schon vor dem Filtern sichtbar ist.

Severity — wie dringend ein Befund ist:

High — sollte vor dem Merge behoben werden; funktionale Fehler oder Sicherheitsprobleme mit realer Auswirkung.
Medium — sollte behoben werden, blockiert aber nicht zwingend.
Low — Hinweis, oft stilistischer oder vorbeugender Natur.

Category — worum es inhaltlich geht:

Bug — fehlerhaftes Verhalten, etwa Nullzugriffe, falsche Randfälle, Race Conditions.
Security — Schwachstellen wie SQL-Injection, XSS, fehlende Validierung oder Autorisierung.
Performance — unnötiger Aufwand, etwa N+1-Abfragen oder Arbeit in heißen Pfaden.
Maintainability — Lesbarkeit, Struktur, Duplikate, fehlende Fehlerbehandlung.

Beide Dimensionen sind orthogonal: Ein Security-Befund kann Low sein, ein Maintainability-Befund High. Die Filter wirken kombiniert (UND-Verknüpfung), All setzt die jeweilige Dimension zurück.

Gruppierung nach Datei

Die Befunde sind nach Datei gruppiert, mit der Anzahl der Kommentare je Datei am rechten Rand. Aufgeklappt zeigt jede Gruppe die einzelnen Kommentare mit Zeilenbezug, Beschreibung des Problems und — soweit vorhanden — einem konkreten Korrekturvorschlag.

Der Zeilenbezug stammt aus einem eigenen Positionierungsschritt und nicht aus einer Schätzung des Modells. Er sollte daher exakt auf die betroffene Stelle zeigen.

Files Reviewed

Diese Karte listet alle geprüften Dateien auf — auch die ohne jeden Befund.

Das ist kein redundanter Inhalt, sondern der entscheidende Gegencheck zu den Review Comments: Nur hier lässt sich unterscheiden zwischen „Datei wurde geprüft und war sauber“ und „Datei taucht nirgends auf, weil sie gar nicht geprüft wurde“. Wenn eine Änderung verdächtig wenige Befunde produziert, ist dieser Abschnitt die erste Anlaufstelle.

Zusammen mit den Coverage-Zählern ergibt sich daraus ein vollständiges Bild der Abdeckung.

Conversations

Hier lässt sich der Ablauf des Reviews nachvollziehen: der Gesprächsverlauf des Agents je Datei bzw. Review-Einheit — die verwendeten Prompts und Regeln, die Tool-Aufrufe (Datei lesen, Codebasis durchsuchen, andere geänderte Dateien einsehen), deren Ergebnisse und die Antworten des Modells.

Typische Anlässe, hier hineinzuschauen:

Falsch-positiver Befund — welchen Kontext hatte der Agent, als er den Befund erzeugte?
Erwarteter Befund fehlt — wurde die relevante Stelle überhaupt gelesen?
Auffälliger Token-Verbrauch — welche Tool-Aufrufe haben den Kontext aufgebläht?
Regelentwicklung — hat eine eigene Regel wie beabsichtigt gegriffen?

Für die tägliche Arbeit ist dieser Abschnitt selten nötig. Für das Tuning von Regeln, Modellen und Konfiguration ist er die wichtigste Quelle.

Typische Arbeitsabläufe

Ergebnis eines Reviews triagieren Status im Header prüfen → Coverage auf Failed prüfen → Review Comments auf High filtern → Befunde abarbeiten → mit Medium fortfahren.

Kosten oder Laufzeit analysieren Duration und LLM Requests mit früheren Sessions vergleichen → File breakdown öffnen → Ausreißer identifizieren → bei Bedarf Filter- oder Bundling-Konfiguration anpassen.

Unerwartetes Ergebnis untersuchen Files Reviewed prüfen, ob die betroffene Datei enthalten ist → falls ja, die zugehörige Conversation öffnen → falls nein, Coverage und Ausschlussregeln prüfen.

Hinweise

Der Screen ist schreibgeschützt. Alle Aktionen — erneutes Review, Wiederaufnahme, Konfigurationsänderungen — laufen über die CLI.
Die dargestellten Daten liegen lokal im Session-Verzeichnis. Der Viewer lädt nichts hoch.
Sessions enthalten Quellcode und Prompts. Beim Teilen von Screenshots oder Exporten gelten dieselben Vertraulichkeitsanforderungen wie für das Repository selbst.

Speicherformat auf der Platte

~/.opencodereview/sessions/
└── <path-encoded-repo-path>/
    └── <session-id>.jsonl

Jede Zeile ist ein Ereignis (llm_request, llm_response, tool_call, …). Zum Speicherplatzsparen einfach ganze Sessiondateien löschen — der Viewer generiert den Index beim nächsten Aufruf neu.

Datenschutz

Die JSONL-Transkripte enthalten alles, was an das LLM gesendet und zurückgegeben wurde, einschließlich Diff-Code. Sie liegen ausschließlich lokal — OCR lädt sie nirgendwohin hoch. Bei sensiblem Code: Sessiondateien regelmäßig löschen, oder in CI mit temporärem HOME arbeiten, damit nichts persistiert wird.

Integrationen

Agent Skill

Registriert OCR als aufrufbaren „Skill“ für Agenten-Frameworks — inklusive Voraussetzungsprüfungen, Aufrufworkflow und Triage-Rubrik (Hoch/Mittel/Niedrig).

Installation:

# Option 1: npx skills add (empfohlen)
npx skills add alibaba/open-code-review --skill open-code-review

# Option 2: manuelles Kopieren (systemweit)
mkdir -p ~/.claude/skills
cp -R /pfad/zu/open-code-review/skills/open-code-review ~/.claude/skills/

# Option 3: für den pi.dev coding agent
pi install npm:pi-open-code-review

Der Skill installiert die ocr-CLI beim ersten Lauf selbst nach, wenn nötig. Ein konfiguriertes LLM muss aber vorab vorhanden sein — der Skill kann das nicht selbst erledigen und hält an, um den Nutzer zu fragen.

Ablauf eines /open-code-review-Aufrufs:

Voraussetzungsprüfung (which ocr, ocr llm test).
Bei Bedarf: automatische CLI-Installation via NPM, ohne Rückfrage.
Kein LLM konfiguriert? → Anhalten, zwei unterstützte Optionen zeigen (Umgebungsvariablen oder ocr config set …), auf API-Schlüssel warten — keine erfundenen Zugangsdaten.
Geschäftskontext aus dem Reviewziel extrahieren (--background).
ocr review --audience agent --background "…" [--commit | --from/--to] ausführen.
JSON-Kommentare nach Hoch/Mittel/Niedrig gruppieren (Bugs/Sicherheitsprobleme = Hoch, Nitpicks und wahrscheinliche Fehlalarme werden stillschweigend verworfen), Markdown-Zusammenfassung rendern.
Bei „review und fix“: sichere Fixes für Hoch/Mittel inline anwenden; sonst vorher fragen.

Anthropic Agent SDK:

from anthropic_agent_sdk import Agent

agent = Agent(
    skill_paths=["/pfad/zu/open-code-review/skills/open-code-review"],
)
agent.run("Review meine gestagten Änderungen — Fokus auf Race Conditions.")

Claude-Code-Plugin (Slash Command)

Installiert einen fertigen Befehl, der OCR Ende-zu-Ende innerhalb von Claude Code ausführt: Diff reviewen, Befunde klassifizieren, automatisch Fixes anwenden.

Installation über Plugin-Marketplace (empfohlen) — innerhalb Claude Code:

/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review

Registriert /open-code-review:review.

Alternativ — Befehlsdatei direkt kopieren:

mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md

(Registriert als /open-code-review, ohne :review-Suffix.)

Nutzung:

/open-code-review:review
/open-code-review:review review this PR against main
/open-code-review:review focus on race conditions in commit abc123

Ohne Argumente → Arbeitsbereich-Modus; mit Commit-Erwähnung → --commit; mit Branch-Vergleich → --from/--to. OCR-Flags können auch direkt durchgereicht werden.

Unterschied zum Agent Skill: Dieser Befehl wendet standardmäßig Fixes automatisch an — die richtige Oberfläche für „review und aufräumen“ statt „zeig mir nur den Diff“.

Delegation Mode

OCR übernimmt die deterministische Ingenieursarbeit (Dateiauswahl, Regelauflösung), während der Host-Agent (Claude Code, Codex, Cursor, Open Code, Qoder, pi.dev, …) den eigentlichen Review mit seiner eigenen LLM-Fähigkeit durchführt. Kein eigener LLM-Endpunkt auf OCR-Seite nötig — die bestehende Subscription-Quote des Host-Agenten wird genutzt.

Wann sinnvoll:

Der Coding-Agent läuft auf einem Abo-Plan und dessen Quote soll wiederverwendet werden.
Nur die „Scaffolding“-Funktion von OCR wird gebraucht (Dateifilterung, Regelauflösung, Ausschlusslogik) — der Host-Agent übernimmt alle LLM-Überlegungen.
Eine eigene Agenten-Pipeline benötigt strukturierte Eingaben (Dateiliste + Regeln) für einen eigenen Review-Schritt.

Voraussetzung:

which ocr || npm install -g @alibaba-group/open-code-review

Keine LLM-Konfiguration nötig — Delegation Mode ruft auf OCR-Seite nie ein LLM auf.

Skill/Command installieren:

# Claude Code — Command
mkdir -p .claude/commands
curl -o .claude/commands/delegate-review.md \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md

# Beliebiger Agent — Skill
npx skills add alibaba/open-code-review --skill open-code-review-delegate

Ablauf:

Vorschau — was reviewt werden soll:ocr delegate preview [--from <ref> --to <ref>] [--commit <hash>] [--exclude <patterns>] Liefert Modus, Ref-Metadaten, Liste der review-fähigen Dateien und Ausschlussgründe.
Regeln für Dateien abrufen:ocr delegate rule <path1> <path2> ... Ausgabe nach gemeinsamem Regeltext gruppiert.
Diffs holen — direkt per Git (git diff HEAD -- <path>, git show <commit> -- <path>, …).
Jede Datei reviewen — Diff aus Schritt 3 + passende Regelgruppe aus Schritt 2 als Checkliste, ggf. mit weiterer Kontextrecherche.
Bericht — Klassifikation nach Schweregrad: Kritisch/Hoch (immer melden), Mittel (mit Kontext melden), Niedrig (stillschweigend verwerfen, außer klar wertvoll).

Vergleich der Integrationsmodi:

Modus	Wer ruft das LLM auf?	Anwendungsfall
Agent Skill	OCR	Agent ruft `ocr review` auf; OCR steuert den vollen Review
Command (Claude Code)	OCR	Slash-Command in Claude Code; OCR steuert den Review
Pi-Paket (`/ocr`)	OCR	Slash-Command + Skill in Pi; OCR steuert den Review
Delegation Mode	Host-Agent	OCR liefert Scaffolding; der Agent steuert den Review

Pi (pi.dev)

Das Paket pi-open-code-review bringt OCR nach demselben Funktionsprinzip wie die Claude-Code- und Codex-Integrationen in Pi: OCR bleibt die Review-Engine, Pi liefert einen Skill für natürlichsprachliche Anfragen und einen Slash-Command für den expliziten Aufruf. Paketseite: https://pi.dev/packages/pi-open-code-review.

Was das Paket mitbringt:

einen Skill open-code-review für natürlichsprachliche Review-Anfragen,
einen einzigen Slash-Command, /ocr, für explizite Review-, Fix- und Scan-Workflows.

Voraussetzungen

/ocr prüft vor jedem Lauf, ob die offizielle OCR-CLI vorhanden ist. Fehlt ocr, wird sie automatisch nachinstalliert:

npm install -g @alibaba-group/open-code-review

OCR benötigt weiterhin seine eigene LLM-Konfiguration, bevor ein Review laufen kann:

ocr llm test

Die Installation dieses Pi-Pakets konfiguriert keine API-Schlüssel und ändert nicht den Modell-Provider von Pi selbst — OCR verwendet ausschließlich seine eigene, separat konfigurierte LLM-Anbindung (siehe Konfiguration).

Installation

Über npm (empfohlen):

pi install npm:pi-open-code-review

Für die lokale Entwicklung aus einem Checkout heraus:

pi install /pfad/zu/pi-open-code-review

Für einen einmaligen Testlauf, ohne das Paket dauerhaft in die Einstellungen zu übernehmen:

pi -e /pfad/zu/pi-open-code-review

Nutzung

/ocr ist der einzige vom Paket bereitgestellte Slash-Command. Er unterstützt sowohl natürlichsprachliche Anfragen als auch präzise OCR-Unterbefehle. review, fix und scan sind dabei Unterbefehle, die auf OCR-Workflows abgebildet werden — keine eigenständigen Pi-Befehle:

/ocr review
/ocr review --from main --to feature-branch
/ocr review --commit abc123
/ocr fix --from main --to feature-branch
/ocr scan --path src

Natürlichsprachliche /ocr-Eingaben werden an den Pi-Agenten zurückgeleitet, der mit Hilfe des open-code-review-Skills selbst entscheidet, ob ein Arbeitsbereich-Review, ein vollständiger Datei-Scan, ein Commit-Review, ein Branch-Vergleich oder ein Fix-Workflow angebracht ist:

/ocr Review meine aktuellen, noch nicht committeten Änderungen.
/ocr Schau dir den Code unter src/auth an — Fokus auf Sicherheitsprobleme.
/ocr Vergleiche diesen Branch mit main und reviewe die Unterschiede.

Der präzise Modus greift automatisch, sobald der Text mit review, fix, scan oder einem Flag wie --commit beginnt. Intern führt die Extension OCR mit maschinenlesbarer Ausgabe aus:

ocr review --format json --audience agent
# bzw. für den Scan-Modus:
ocr scan --format json --audience agent

Verhalten

Der Standard-Review prüft Staged-, Unstaged- und Untracked-Änderungen im Arbeitsbereich — identisch zum Verhalten der reinen OCR-CLI.
Fehlt ocr, versucht /ocr die offizielle @alibaba-group/open-code-review-CLI nachzuinstallieren (analog zum Codex-Plugin-Ablauf).
Vor jedem Review führt /ocr zunächst ocr llm test aus und stoppt mit einer Setup-Anleitung, falls OCRs Modell-Provider nicht konfiguriert ist.
/ocr fix bedeutet: zunächst reviewen, danach Pi bitten, präzise High- und Medium-Befunde zu beheben.
/ocr review --preview und /ocr scan --preview zeigen OCRs Text-Vorschau direkt an, statt JSON zu erzwingen.
/ocr review bearbeitet nie Dateien, außer der Nutzer bittet ausdrücklich um eine Behebung (Fix).
Bei natürlichsprachlichen /ocr-Anfragen interpretiert der Pi-Agent die Anfrage über den open-code-review-Skill, statt sie als OCR-Flags zu parsen.
Befunde mit geringer Konfidenz werden von den Skill-Regeln standardmäßig herausgefiltert, außer der Nutzer bittet explizit um alle Kommentare.
Das Paket leitet nur eine konservative Allowlist an OCR-Flags durch, um unbeabsichtigtes Shell-Verhalten zu vermeiden.

FAQ — häufige Probleme

Konfiguration & Start

no valid LLM endpoint configured OCR hat die komplette Endpunkt-Auflösungskette durchlaufen und kein vollständiges (URL, Token, Modell)-Tripel gefunden. Entweder ocr config set llm.url/llm.auth_token/llm.model setzen, OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL exportieren, oder — bei bereits vorhandenem Claude-Code-Setup — ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ANTHROPIC_MODEL exportieren. Danach ocr llm test zur Verifikation.

ocr llm test zeigt die falsche Quelle OCR nutzt das erste vollständige Tripel, nicht das letzte. Enthält die Konfigurationsdatei bereits alle drei llm.*-Schlüssel, werden Umgebungsvariablen ignoriert. Um der Umgebung Vorrang zu geben: Konfigurationsschlüssel löschen oder auf die neuen Werte umsetzen.

401 / 403 von ocr llm test Token fehlt Scope, ist abgelaufen oder falscher Anbieter. Anthropic und OpenAI nutzen unterschiedliche Auth-Header und URL-Formen — llm.use_anthropic muss zur URL passen: Anthropic-URLs enden auf /v1/messages (use_anthropic=true), OpenAI-kompatible auf /v1/chat/completions (use_anthropic=false).

not a git repository ocr review läuft git diff gegen das aktuelle Verzeichnis. Entweder ins Repo wechseln oder --repo /pfad/zum/repo übergeben.

„No tool calls parsed“ (lokale Modelle / Ollama)

[ocr] No tool calls parsed for src/foo.go, retrying...
[ocr] Max tool requests reached for src/foo.go.

OCR steuert den Review vollständig über Tool-Aufrufe. Das Modell muss natives Tool-Calling unterstützen. Ein Modell, das Tool-Aufrufe nur im Text (oder in <think>-Blöcken) beschreibt, funktioniert nicht mit OCR, egal wie der Prompt angepasst wird (qwen3.8-27B ist ein gängiges Beispiel). Modelle mit nativer Tool-Unterstützung, z. B. qwen3, funktionieren einwandfrei. Für Ollama: Modelle mit Tools-Tag verwenden (https://ollama.com/search?c=tools).

Unterstützt das Modell Tools, ist aber auf lokaler Hardware langsam: LLM-Timeout erhöhen (siehe Timeouts).

Filterung & Regeln

Meine Datei wird nicht reviewt ocr review --preview (kostenlos) zeigt jede Kandidatendatei mit dem Grund für Behalten/Verwerfen:

Grund	Lösung
`binary`	nichts zu tun — Binärdateien haben keinen reviewbaren Text
`user_exclude`	Muster aus der eigenen `exclude`-Liste entfernen
`unsupported_ext`	Endung zur `include`-Liste hinzufügen
`default_path`	Datei zu `include` hinzufügen — überschreibt eingebaute Testdatei-Ausschlüsse
`deleted`	nichts zu tun — kein neuer Inhalt zum Reviewen

Meine benutzerdefinierte Regel feuert nicht ocr rules check <file-path> zeigt Schicht und Glob-Muster durchgängig. Falsche Schicht meist wegen Deklarationsreihenfolge — spezifischere Regel weiter nach vorne in rules verschieben.

Klammererweiterung funktioniert nicht {ts, tsx} mit Leerzeichen matcht tsx still nicht — Leerzeichen entfernen.

Reviews

Datei zeigt null Kommentare — wurde sie überhaupt reviewt? ocr viewer öffnen, die main_task-Spur der Datei prüfen: Tool-Aufrufe + endet mit task_done = sauberer Review. Kein main_task-Block = Datei wurde vor dem Review gefiltert (siehe Filterung & Regeln oben).

Kommentare mit start_line: 0 und end_line: 0 OCR konnte den Kommentar nicht präzise verankern — meist paraphrasierter existing_code oder ungewöhnliche Diff-Formatierung (CRLF, gemischte Tabs/Spaces). Der Kommentar ist trotzdem real, nur nicht automatisch platziert.

Token-Schwelle überschritten

[ocr] WARNING: prompt tokens (94000) exceed 80% of max_tokens(58888) for src/big.sql

Datei zum exclude hinzufügen (falls autogeneriert), großen Refactor in kleinere Commits aufteilen, oder --commit-Modus für eine Serie kleiner Commits nutzen.

Planungsphase dauert lange bei kleiner Datei ocr review --preview prüfen — liegt lines.changed über PLAN_MODE_LINE_THRESHOLD (Standard 50), läuft die Planungsphase absichtlich.

„Max tool requests reached“ Modell hat 30 (MAX_TOOL_REQUEST_TIMES) Runden ohne task_done verbraucht. Bereits erzeugte Kommentare bleiben erhalten. Häufige Ursachen: Modell befolgt „task_done bei Fertigstellung“ nicht gut genug (stärkeres Modell wählen), ein Tool schlägt wiederholt fehl, oder die Datei ist schlicht groß (--max-tools <n> anpassen).

Manche Sub-Agenten scheitern; der Lauf gibt trotzdem Exit-Code 0 Das ist Beabsichtigt. Ein fehlerhafter Sub-Agent soll nicht einen 20-Dateien-Review kippen. Exit-Code 0, sobald irgendetwas erfolgreich war; nur ein vollständig fehlgeschlagener Lauf (null erfolgreiche Sub-Agenten) liefert einen Fehler-Exit-Code.

CI-Lauf ist deutlich langsamer als lokal Meist Modell-Rate-Limits (--concurrency senken) oder kalter Cache (erster Lauf nach Deploy profitiert nicht vom Prompt-Caching).

Ausgabe & Integration

--audience agent zeigt trotzdem Fortschrittszeilen Das ist vermutlich stderr. Zum vollständigen Unterdrücken: ocr review --audience agent 2>/dev/null.

JSON-Ausgabe ist { "files_reviewed": 0, "comments": [] } Absichtlich — unterscheidet „nichts zu reviewen“ von „keine Befunde in reviewten Dateien“ (dann schlicht ein leeres []).

Wo liegen Session-JSONLs?

~/.opencodereview/sessions/<path-encoded-repo-path>/<session-id>.jsonl

Pfadkodierung: / und \ → -, : → _. Mit ocr viewer durchstöbern; Verzeichnis löschen für kompletten Verlaufs-Reset.

Performance & Kosten

Wie sehe ich, was Tokens kosten? Telemetrie aktivieren und ocr.llm.tokens_used, ocr.llm.requests_total, ocr.llm.request_duration_seconds beobachten (siehe Telemetrie).

Warum sind meine Reviews so teuer? Planungsphase kostet einen extra LLM-Aufruf ab 50 Zeilen; MAX_TOOL_REQUEST_TIMES = 30 ist großzügig bemessen — je mehr Runden genutzt werden, desto teurer; Speicherkompression selbst ist ein LLM-Aufruf.

Wie reduziere ich LLM-Aufrufe? include-Liste einschränken, --concurrency bei Burst-Preisen senken, --background nutzen (oft entfallen dadurch file_read/code_search-Roundtrips).

Datenschutz & Sicherheit

Sendet OCR meinen Code irgendwohin? OCR sendet Diffs (und optional Read-Tool-Ausschnitte) an den konfigurierten LLM-Endpunkt. Sonst verlässt nichts die eigene Maschine. Session-JSONLs und Regeldateien sind rein lokal. Das content_logging-Flag gatet aktuell keinen Codepfad. Prompt-/Antwortinhalte werden nie an einen Collector exportiert, unabhängig vom Wert.

Kann ich Geheimnisse vor dem Senden redigieren? Kein eingebautes Feature. Empfohlen: Secrets grundsätzlich nicht committen, Dateien mit Secret-Material in exclude aufnehmen, git diff --no-textconv-Filter oder Pre-Commit-Redaktion nutzen. Eine native „Redaktionsregel“ ist auf der Roadmap.

Deinstallation

npm uninstall -g @alibaba-group/open-code-review        # NPM-Installation
sudo rm /usr/local/bin/ocr                              # Binary-Installation
rm -rf ~/.opencodereview                                # kompletter Zustand

Schnellreferenz-Tabellen

Wichtigste Standardwerte

Einstellung	Standardwert
Prompt-Token-Obergrenze pro Datei (`MAX_TOKENS`)	58.888
Maximale Tool-Aufruf-Runden pro Datei	30
Concurrency (parallele Dateien)	8
Timeout pro Datei	10 Minuten
LLM-HTTP-Timeout	300 Sekunden
Schwellwert für die Planungsphase	50 geänderte Zeilen
Diff-Kontextzeilen	3
Viewer-Standardadresse	`localhost:5483`
NPM-Update-Cooldown	18 Minuten

Wichtigste Umgebungsvariablen

Variable	Zweck
`OCR_LLM_URL` / `OCR_LLM_TOKEN` / `OCR_LLM_MODEL`	Endpunkt-Trias (Fallback-Ebene)
`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_MODEL`	Wiederverwendung der Claude-Code-Konfiguration
`OCR_LLM_TIMEOUT`	LLM-Anfrage-Timeout in Sekunden
`OCR_NO_UPDATE`	Automatische NPM-Updates deaktivieren
`OCR_UPDATE_INTERVAL`	Update-Check-Intervall in Minuten
`OCR_ENABLE_TELEMETRY`	Telemetrie aktivieren
`OTEL_EXPORTER_OTLP_ENDPOINT` / `_PROTOCOL`	OTLP-Zielkonfiguration
`OCR_VIEWER_ALLOWED_HOSTS`	Wildcard-Host-Allowlist für den Viewer
`OCR_CONTENT_LOGGING`	reserviert, derzeit wirkungslos

Wichtigste Dateipfade

Pfad	Inhalt
`~/.opencodereview/config.json`	Zentrale Konfiguration
`~/.opencodereview/rule.json`	Globale Regeln
`<repo>/.opencodereview/rule.json`	Projektregeln
`~/.opencodereview/sessions/…`	JSONL-Session-Transkripte

Diese Anleitung wurde auf Basis der offiziellen OCR-Dokumentation (open-codereview.ai) zusammengestellt und ins Deutsche übertragen. Für die jeweils aktuellste Fassung und den Quellcode siehe das GitHub-Repository.

OpenCodeReview (OCR)

Überblick & Grundkonzept

Installation

NPM (empfohlen)

Homebrew (macOS / Linux)

MacPorts (macOS)

Installationsskript (curl | sh)

GitHub-Release-Binary direkt

Aus dem Quellcode bauen

Installation prüfen

Wo OCR seinen Zustand speichert

Schnellstart (QuickStart)

Schritt 1 — CLI installieren

Schritt 2 — LLM konfigurieren

Schritt 3 — Verbindung testen

Schritt 4 — Ersten Review starten

Konfiguration

Modell konfigurieren

Custom: eigener Provider

Manual: Endpunkt direkt setzen

Official: eingebaute Provider

Basis-URL eines eingebauten Providers überschreiben

Benutzerdefinierte Provider

Timeouts

Zusätzliche Retry-Statuscodes

Prompt-Limit pro Datei

Verbindung prüfen

Bestehende Umgebungsvariablen wiederverwenden

CC-Switch nutzen

Providerspezifische Felder senden

Sitzungsaffinität für Prompt-Caching

Review-Sprache konfigurieren

CLI-Referenz

Übersicht

ocr review

Flags

Modelwahl pro Lauf

Modi

Unterbrochene Reviews fortsetzen

Ausgabeformate

ocr scan

ocr session

ocr rules check

ocr config

ocr llm

ocr viewer

ocr completion

ocr version

Tipps & Fallstricke

Die eingebauten Tools

Verfügbarkeit pro Phase

task_done

code_comment

file_read

file_read_diff

file_find

code_search

Tools anpassen

Review-Regeln (Rules)

Prioritätskette

Regeldatei-Format (Ebenen 1–3)

Regelauflösung pro Datei

ocr rules check — welche Regel gewinnt

Rezepte

MCP-Server als Werkzeugquelle

Wann sinnvoll

Konfiguration

Namenskonflikte

Fehlerdiagnose

Session Viewer (Web-UI)

Starten

Drei Seiten (Full Scan)

Session-Detail

Grundkonzept: Was ist eine Session?

Aufbau des Screens

Kopfzeile

Session-Header

Review-Modi

Status

Coverage

`ocr review`

`ocr scan`

`ocr session`

`ocr rules check`

`ocr config`

`ocr llm`

`ocr viewer`

`ocr completion`

`ocr version`

`task_done`

`code_comment`

`file_read`

`file_read_diff`

`file_find`

`code_search`

`ocr rules check` — welche Regel gewinnt