Code Review CLI

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

Current MVP

• review staged
• review staged --format json
• review staged --ai
• review staged --architecture
• review staged --architecture-only
• review diff --base main
• review file src/example.ts
• review explain <finding-id>
• review ci --base main
• staged diff collection
• diff-against-base collection
• full-file review mode
• unified patch parsing
• deterministic findings for a few high-signal cases
• optional AI semantic review with OpenAI Responses API
• advisory architecture findings from both AI and deterministic heuristics
• architecture metadata in terminal/explain/Markdown/JSON output when principle or pattern context is available
• terminal, JSON, Markdown, and SARIF output
• category-grouped terminal and Markdown findings
• repo config via .codereviewrc.json
• saved last-review history inside .git/code-review-cli

Run

On Windows, the easiest local entrypoint is the wrapper script:

.\review.cmd staged

It forwards to the TypeScript CLI for you, so you do not need to type node --experimental-strip-types each time.

node --experimental-strip-types .\src\index.ts review staged

node --experimental-strip-types .\src\index.ts review staged --format json

$env:OPENAI_API_KEY="your_api_key"
node --experimental-strip-types .\src\index.ts review staged --ai

node --experimental-strip-types .\src\index.ts review staged --architecture

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

Or add a local .env file in the repo you want to review:

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

node --experimental-strip-types .\src\index.ts review diff --base main

node --experimental-strip-types .\src\index.ts review file .\src\index.ts

node --experimental-strip-types .\src\index.ts review ci --base main --fail-on high --format sarif

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

You can also use the wrapper with the same commands:

.\review.cmd file .\fixtures\repos\architecture-smells\src\pricing\policies.ts --architecture-only
.\review.cmd config show

Build

To build a plain JavaScript dist version for running without the experimental strip-types flag:

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

Until dependencies are installed, the wrapper script is the smoothest local workflow on Windows.

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".

Explain Findings

Each review command saves the latest review result in .git/code-review-cli/last-review.json.

After running a review:

node --experimental-strip-types .\src\index.ts review explain <finding-id>

Test

node --experimental-strip-types .\tests\run.ts

The test harness now includes fixture-driven regression coverage using realistic 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

To run a quick end-to-end local demo flow:

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

Notes

This repo is intentionally dependency-light for the first implementation slice so we can keep building even while package manager setup is being repaired.

Reviewer Spec

The current rule inventory and AI reviewer behavior are documented in docs/REVIEWER_SPEC.md.

Architecture

The living technical architecture reference is documented in docs/ARCHITECTURE.md.