Agentic code review organized around behavioral Units, two-stage evidence review, and language/project knowledge. Built on open-code-review. ｜ 中文见 README.zh-CN.md
Code review is not “send every changed file to a model.” File boundaries describe storage, not behavior; a diff alone is often too narrow, while reading the whole repository is usually too expensive and still cannot reveal unstated business rules.
ccr follows three principles:
- Review behavior, not files. A review should cover the smallest scope that explains a change and its effects. ccr calls that scope a Unit.
- Separate discovery from verification. Finding a plausible issue is open-ended; proving that it is real, caused by the current change, actionable, and new is narrower. Different jobs deserve different agent loops.
- Bring relevant knowledge, not maximum context. Language structure and project structure decide what belongs together and which nearby evidence is worth showing to the model.
ccr does not try to enumerate every possible defect. It focuses bounded agent exploration on concrete mistakes that are easy to miss while implementing a requirement: broken caller assumptions, boundary handling, error paths, API misuse, and similar reviewable failures. Syntax remains lint's job; hidden business constraints still need explicit background or authored knowledge.
A Unit is one behavioral review scope. Depending on the change, it can be:
- a function when one symbol is the natural boundary;
- a file when the diff touches only one reviewable file;
- a cross-file call chain when changed functions collaborate and separate file reviews would rediscover the same context.
This makes review granularity more flexible than file-by-file review. The practical goal is for Review 1 to use no more loops than there are reviewable files, and fewer when related cross-file changes can be reviewed together.
| stage | responsibility | output | public-prosecution analogy |
|---|---|---|---|
| Unit Review (Review 1) | explore a Unit, follow evidence, identify plausible defects | Hypothesis |
investigation proposes a case theory |
| Hypothesis Review (Review 2) | independently check source, diff, baseline, impact, attribution, and duplication | Assessment |
prosecutor reviews whether evidence supports the allegation |
| Trial | apply deterministic delivery gates | Finding or rejection |
court gate decides what may be delivered |
The analogy explains separation of duties; these are code-review stages, not legal simulations. Review 1 is encouraged to discover. Review 2 is encouraged to disprove weak hypotheses. Trial is deterministic so incomplete or unsupported work cannot silently become a public comment.
Two knowledge foundations support Unit formation and both review stages:
| knowledge | what it contributes |
|---|---|
| Language Knowledge | syntax-aware symbols, spans, definitions, references, calls, imports, documentation, and extraction/matching of authored contracts |
| Project Knowledge | Repository and Component boundaries, file roles, entrypoints, handlers, manifests, locks, and other project conventions |
Some context types—such as spec, case, rule, link, and source documentation—depend on language parsing even though they are not “language knowledge” by themselves. spec-case remains an optional way to author and distribute this contract context; ccr also works without it.
Design details: Kernel · Unit · Unit Review · Hypothesis Review · Language · Harness and observability
git clone https://github.com/compforge/case-code-review && cd case-code-review
make install # installs `ccr` into ~/.local/bin; re-signs on macOS
# or: go install github.com/qiankunli/case-code-review/cmd/ccr@latestccr config provider # choose or add a provider
ccr config model # choose a model
ccr llm test # verify connectivityConfiguration lives in ~/.casecodereview/config.json. Built-in and OpenAI-compatible custom providers can also be configured non-interactively; see ccr config --help.
ccr review # staged + unstaged + untracked changes
ccr review --from main --to my-branch # branch against merge base
ccr review --commit abc123 # one commit against its first parent
ccr review --background "requirement" # add business or requirement context
ccr review --format json # machine-readable output for CI/botsFor continuous PR/MR review, pass earlier delivered findings with --history prior.json. The forge comments are the durable source; the caller fetches them for each revision so ccr can distinguish new findings from repeat delivery.
ccr review --preview # changed files and their review/exclusion roles
ccr review --dry-run # formed Units and assembled context, without an LLM call
ccr review --dry-run --format jsonccr viewer # sessions, token/time/tool totals, prompts and decisionsSession JSONL preserves the actual messages, model responses, tool calls, artifacts, warnings, and completion state. The Viewer turns that trace into run-level statistics and per-loop timelines for diagnosing quality, cost, and incomplete reviews.
Place a generated spec.json at .casecodereview/spec.json, pass --spec, or configure user-level contracts to add authored spec/case/rule/link context. Named feature gates support ablation, for example:
ccr review --feature caller_callee=off
ccr review --feature callchain=off
ccr review --feature doc=offRun ccr review --help for the full command and feature list.
Actively developed. Current foundations include project-aware file roles, language analysis, Unit formation, two-stage evidence review, cross-revision history, bounded agent execution, and an observable session viewer.
Apache-2.0 (see LICENSE / NOTICE).