Code Review CLI

Local-first CLI for reviewing git changes before commit or PR creation.

Demo

Code_reviewer.mp4

A 22-second tour of review staged and review staged --architecture. Finding titles come from the real rule set; the file names and line numbers shown are illustrative.

What it is

A CLI that reads your staged changes, a diff against a base ref, or a single file and reports findings from 39 deterministic rules. It can optionally add an AI semantic review (OpenAI Responses API) and advisory architecture suggestions (design principles and patterns). Everything runs locally, and the repo has no runtime dependencies (TypeScript is a dev dependency only).

Features

• Review modes: staged changes, diff against a base ref, full file, and a CI mode with a severity gate
• 39 deterministic rules for high-signal cases (backend, frontend, Python, framework and core checks)
• Optional AI semantic review (--ai)
• Advisory architecture findings from deterministic heuristics plus optional AI (--architecture, --architecture-only), with principle and pattern metadata (strategy, repository, factory, adapter, builder, facade, observer, command)
• Output formats: terminal, JSON, Markdown, SARIF; findings are grouped by category
• Repo config via .codereviewrc.json
• review explain <finding-id> for the last saved review, stored in .git/code-review-cli

Supported file extensions: .ts, .tsx, .js, .jsx, .mjs, .cjs, .py, .java, .cs, .go, .sql, .sh.

Requirements

• Node.js 22 or newer (engines in package.json)
• git
• OPENAI_API_KEY only if you use AI review
• npm install is only needed for npm run build (installs TypeScript)

Install

No install is needed to run from source:

git clone https://github.com/AlSh007/prereview_cli.git
cd prereview_cli
node --experimental-strip-types ./src/index.ts review staged

Run it from inside the repo you want to review, pointing at this repo's src/index.ts. The package is private, so it is not published to npm.

Usage

Examples below use node --experimental-strip-types ./src/index.ts (npm script npm run review -- <args> does the same). On Windows, .\review.cmd wraps it and adds the review prefix for you, e.g. .\review.cmd staged.

# Staged changes
node --experimental-strip-types ./src/index.ts review staged
node --experimental-strip-types ./src/index.ts review staged --format json

# Diff against a base ref
node --experimental-strip-types ./src/index.ts review diff --base main

# A single file
node --experimental-strip-types ./src/index.ts review file src/example.ts

# AI and architecture lanes
node --experimental-strip-types ./src/index.ts review staged --ai
node --experimental-strip-types ./src/index.ts review staged --architecture
node --experimental-strip-types ./src/index.ts review staged --architecture-only

# CI: exits 1 if any finding is at or above --fail-on (default medium)
node --experimental-strip-types ./src/index.ts review ci --base main --fail-on high --format sarif

# Explain a finding from the last review
node --experimental-strip-types ./src/index.ts review explain <finding-id>

# Config
node --experimental-strip-types ./src/index.ts config init
node --experimental-strip-types ./src/index.ts config show
node --experimental-strip-types ./src/index.ts config validate

Flags:

• --format terminal|json|markdown|sarif
• --ai / --no-ai to force AI review on or off (otherwise ai.enabled from config)
• --architecture adds architecture findings; --architecture-only skips the standard rules and correctness AI findings
• --base <ref> (required for diff and ci)
• --fail-on high|medium|low|info|none (ci only)

Architecture review does not require an API key for the deterministic architecture rules. If OPENAI_API_KEY is present, the architecture AI lane also runs and enriches the result.

AI configuration

Set OPENAI_API_KEY in your shell, or in a .env file in the working directory or repo root:

OPENAI_API_KEY=your_api_key
OPENAI_MODEL=gpt-5.2-codex
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_RESPONSE_FORMAT=json_schema

For providers that reject strict JSON schema and only support JSON-object mode, set OPENAI_RESPONSE_FORMAT=json_object. These variables override ai.model, ai.apiBaseUrl and ai.responseFormat from the config file.

Config

Create .codereviewrc.json in the repo root:

{
  "ignoredPaths": ["dist", "generated"],
  "disabledRules": ["core.large-diff"],
  "maxFiles": 20,
  "outputFormat": "terminal",
  "ai": {
    "enabled": false,
    "model": "gpt-5.2-codex",
    "apiBaseUrl": "https://api.openai.com/v1",
    "responseFormat": "json_schema"
  },
  "architecture": {
    "enabled": false,
    "mode": "advisory",
    "maxFindings": 5,
    "minConfidence": 0.65,
    "principles": {
      "single-responsibility": true,
      "open-closed": true
    },
    "patterns": {
      "strategy": true,
      "repository": true
    }
  }
}

outputFormat also supports "json", "markdown", and "sarif".

Per-rule overrides are also supported: "rules": { "<ruleId>": { "enabled": false, "severity": "low" } }. Valid architecture principles: single-responsibility, open-closed, liskov, interface-segregation, dependency-inversion. architecture.mode is advisory or architecture-only. See docs/REVIEWER_SPEC.md for the rule inventory.

Build

To build a plain JavaScript dist version that runs without the experimental strip-types flag:

npm install
npm run build
node ./dist/index.js review staged

Test

npm test

The test harness includes fixture-driven regression coverage using sample repos under fixtures/repos for:

• Express / backend flows
• Next.js / frontend and API route flows
• FastAPI / Python backend flows
• architecture-smell coverage, including repository/strategy/factory/adapter/builder/facade/observer/command cases

Smoke Test

A quick end-to-end local demo flow (Windows PowerShell):

powershell -ExecutionPolicy Bypass -File .\scripts\smoke-test.ps1

Tech stack

TypeScript run directly by Node 22 (--experimental-strip-types), compiled with tsc for dist. No runtime dependencies. AI calls go to an OpenAI-compatible Responses API endpoint.

Limitations

• MVP: the deterministic rules cover a limited set of high-signal cases, not full static analysis
• AI and architecture AI lanes need OPENAI_API_KEY; findings from them are advisory
• Only the file types listed above are reviewed
• The package.json bin entry points at the TypeScript source, so it needs a Node with --experimental-strip-types support; the package is private and not published
• review.cmd, review.ps1 and the smoke test are Windows/PowerShell helpers; on macOS/Linux call node directly

Docs

• Reviewer spec: rule inventory and AI reviewer behavior
• Architecture: technical architecture reference
• Architecture review extension