GrandCru

AI code review with character. The Sommelier reviews your code like a questionable bottle of wine.

What is this?

GrandCru is a CLI tool that gives you real code review — issues, line numbers, fixes — delivered by a pretentious French wine sommelier. Bring your own key (you provide your Anthropic API key), zero server infrastructure.

Every review includes Parker Points (0-100), a vintage verdict, and tasting notes (nose, palate, finish) alongside actionable technical feedback.

Strip away the comedy and the feedback is still worth reading.

Quick Start

npm install -g grandcru
grandcru config --key sk-ant-your-key-here
grandcru review src/index.ts

Usage

Review a single file:

grandcru review src/index.ts

Review a directory:

grandcru review src/

Review only changed files (git diff):

grandcru review --diff

Review only staged files:

grandcru review --staged

Triage files by suspicion (zero API calls):

grandcru triage src/

Triage then review top suspicious files:

grandcru triage src/ -y

Dry run (estimate cost without making API calls):

grandcru review src/ --dry-run

JSON output (pipe-friendly):

grandcru review src/index.ts -f json

Markdown output (reports):

grandcru review src/ -f markdown

CI mode (non-interactive, JSON default):

grandcru review --diff --ci

Skip cost confirmation:

grandcru review src/ -y

Verbose diagnostics:

grandcru review src/ --verbose

Smart Triage

Triage ranks your files by "suspicion score" using 8 static heuristics — zero API calls, zero cost. The Sommelier assesses each file's complexity before you decide what deserves a full review.

grandcru triage src/

Heuristics: line count, function length, nesting depth, TODO/FIXME density, broad catch blocks, weak typing (any/Dict), import count, comment-to-code ratio. Each produces a 0-10 score, weighted and summed to 0-100.

Small, clean files earn P2V (Price-to-Value) awards — the Sommelier's recognition for code that "punches above its weight."

After triage, confirm to pipe the top suspicious files directly into a full API review:

grandcru triage src/ -y          # Auto-confirm review of top 10
grandcru triage src/ -n 5        # Review top 5 instead
grandcru triage src/ -f json     # Machine-readable triage output
grandcru triage src/ --no-review # Triage only, no review prompt

Git Integration

Review only what changed — skip unchanged files entirely:

grandcru review --diff           # Changed files since HEAD
grandcru review --staged         # Staged files only

Git flags are mutually exclusive with path arguments. Binary and deleted files are filtered automatically.

CI Mode

Run GrandCru in CI pipelines with zero interactive prompts:

grandcru review --diff --ci

CI mode is auto-detected via process.env.CI or non-TTY stdout. It defaults to JSON output, routes progress to stderr, and uses exit codes: 0 = no issues, 1 = issues found, 2 = tool error.

See docs/github-actions.md for GitHub Actions workflow examples.

Review Caching

Reviews are cached based on SHA-256 hash of file content + model + thinking config. Re-reviewing unchanged files skips the API call entirely and shows cost savings.

grandcru review src/             # First run: all API calls
grandcru review src/             # Second run: cache hits, $0.00
grandcru review src/ --no-cache  # Bypass cache for this run
grandcru cache clear             # Delete all cached reviews

Cache is stored in .grandcru-cache/ (add to .gitignore).

The Character

GrandCru uses a dual-channel approach: real issues get real fixes, but they're delivered with wine metaphors and tasting notes. The Sommelier is the distribution mechanic, not the product.

Every review includes:

• Parker Points — A numeric score (0-100) for overall code quality
• Vintage Verdict — Summary judgment with wine terminology
• Tasting Notes — Nose (first impressions), palate (depth of issues), finish (lingering concerns)
• Technical Issues — Line numbers, severity, descriptions, and suggested fixes

The character makes the feedback memorable. The analysis makes it actionable.

Supported Languages

| Language | Extensions | |------------|-------------------------------| | TypeScript | .ts, .tsx | | JavaScript | .js, .jsx, .mjs, .cjs | | Python | .py | | Go | .go | | Rust | .rs |

Configuration

Global config: ~/.grandcru/config.json (set via grandcru config --key)

Project config: .grandcrurc in project root

Config options:

| Option | Description | Default | |-----------------|--------------------------------------------------|-----------------------------| | apiKey | Anthropic API key | (required) | | model | Claude model to use | claude-sonnet-4-5-20250929 | | thinking | Enable extended thinking for deeper analysis | true | | ignorePatterns| Glob patterns to exclude from review | [] |

Override precedence:

1. CLI flags (--key)
2. Environment variable (ANTHROPIC_API_KEY)
3. Project config (.grandcrurc)
4. Global config (~/.grandcru/config.json)
5. Defaults

Example .grandcrurc:

{
  "model": "claude-sonnet-4-5-20250929",
  "thinking": true,
  "ignorePatterns": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "coverage/**"
  ]
}

See .grandcrurc.example for a full template.

Cost

GrandCru uses Claude Sonnet 4 ($3/$15 per million tokens input/output).

• Extended thinking: Enabled by default. Adds ~40% cost premium but provides better analysis.
• Typical file review: $0.01-0.05 depending on file size and issues found.
• Triage is free: grandcru triage uses zero API calls — purely local static analysis.
• Caching saves money: Unchanged files are served from cache at $0.00.
• Use --dry-run to estimate costs before committing.
• Use --no-thinking to disable extended thinking and reduce costs.

Multi-file reviews show a cost confirmation prompt at $0.50 threshold. Use --yes to bypass.

Output Formats

Terminal (default): Screenshot-worthy output with monochrome + gold accent theme. Perfect for sharing reviews on Twitter/X.

JSON (-f json): Structured output for piping to other tools. Includes both clinical and character fields — use jq to filter.

Markdown (-f markdown): Report-style output with collapsible tasting notes and a summary cellar report for multi-file reviews.

License

MIT — see LICENSE