Grippy Code Review

Open-source AI code review agent. Your model, your infrastructure, your rules.

Grippy reviews pull requests using any OpenAI-compatible model — GPT, Claude, or a local LLM running on your own hardware. It indexes your codebase into a vector store for context-aware analysis, then posts structured findings with scores, verdicts, and escalation paths. It also happens to be a grumpy security auditor who secretly respects good code.

Why Grippy?

• Your model, your infrastructure. Bring your own model. No SaaS dependency, no per-seat fees. Run GPT-5 through OpenAI, Claude through a compatible proxy, or a local model via Ollama or LM Studio.

• Codebase-aware, not diff-blind. Grippy embeds your repository into a LanceDB hybrid search index (vector + full-text) and searches it during review. It understands the code around the diff, not just the diff itself. Most OSS alternatives paywall this behind a hosted tier.

• Cross-PR memory, not amnesia. Grippy builds a knowledge graph of your codebase — tracking files, reviews, findings, and import dependencies across every PR. It knows which modules are blast-radius risks, which files have recurring findings, and which authors have patterns worth watching. Tools like CodeRabbit, Greptile, and Qodo charge $20–38/seat/month for comparable cross-PR context. Here, it's free and open-source.

• Structured output, not just comments. Every review produces typed findings with severity, confidence, and category. A score out of 100. A verdict (PASS / FAIL / PROVISIONAL). Escalation targets for findings that need human attention.

• Security-first, not security-added. Grippy is a security auditor that also reviews code, not the other way around. Dedicated audit modes go deeper than a general-purpose linter.

• Deterministic rules, not just LLM guesses. A built-in rule engine runs 10 security rules against every diff before the LLM sees it. Findings are guaranteed — not hallucinated — and the profile gate can fail CI on critical severity hits, independent of model output.

• MCP server — use Grippy as a local diff auditor from Claude Code, Cursor, or Claude Desktop via the Model Context Protocol.

• It has opinions. Grippy is a grumpy security auditor persona, not a faceless bot. Good code gets grudging respect. Bad code gets disappointment. The personality keeps reviews readable and honest.

What it looks like

An inline finding on a PR diff:

CRITICAL | security | confidence: 95

SQL injection via string interpolation

query = f"SELECT * FROM users WHERE id = {user_id}" constructs a SQL query from unsanitized input. Use parameterized queries.

grippy_note: I've seen production databases get wiped by less. Parameterize it or I'm telling the security team.

A review summary posted as a PR comment:

Score: 45/100 | Verdict: FAIL | Complexity: STANDARD

3 findings (1 critical, 1 high, 1 medium) | 1 escalation to security-team

"I've reviewed thousands of PRs. This one made me mass in-progress a packet of antacids."

Quick start

GitHub Actions (OpenAI)

Add .github/workflows/grippy-review.yml to your repo:

name: Grippy Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    name: Grippy Code Review
    runs-on: ubuntu-latest
    steps:
      - uses: step-security/harden-runner@a90bcbc6539c36a85cdfeb73f7e2f433735f215b  # v2.15.0
        with:
          egress-policy: audit

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6

      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
        with:
          python-version: '3.12'

      - name: Install Grippy
        run: pip install "grippy-mcp"

      # Cache the vector index to avoid re-indexing on every push
      - name: Cache Grippy data
        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306  # v5
        with:
          path: ./grippy-data
          key: grippy-${{ github.event.pull_request.number }}-${{ github.sha }}
          restore-keys: grippy-${{ github.event.pull_request.number }}-

      - name: Run review
        id: review
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_EVENT_PATH: ${{ github.event_path }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GRIPPY_MODEL_ID: gpt-4.1
        run: grippy

Want LLM-only review without the rule engine? Set GRIPPY_PROFILE: general. For stricter gating (fail on WARN+), use strict-security. See examples/ for more workflow variants.

GitHub Actions (self-hosted LLM)

Grippy works with any OpenAI-compatible API endpoint, including Ollama, LM Studio, and vLLM. We recommend Devstral-Small 24B at Q4 quantization or higher — tested during development for structured output compliance and review quality. See the Self-Hosted LLM Guide for full setup instructions.

Local development

# OpenAI (default, included in base install)
pip install "grippy-mcp"

# Anthropic
pip install "grippy-mcp[anthropic]"

# Google (Gemini)
pip install "grippy-mcp[google]"

# Groq
pip install "grippy-mcp[groq]"

# Mistral
pip install "grippy-mcp[mistral]"

# Or with uv
uv add "grippy-mcp[anthropic]"

MCP Server

Quick start (zero install)

uvx grippy-mcp serve

Or install globally:

pip install grippy-mcp
grippy serve

Grippy runs as an MCP server for local git diff auditing — no GitHub Actions required.

Two tools:

Scope options (both tools):

• "staged" — staged changes (git diff --cached)

• "commit:<ref>" — a specific commit (e.g. "commit:HEAD")

• "range:<base>..<head>" — commit range (e.g. "range:main..HEAD")

Install into your MCP client:

python -m grippy install-mcp          # registers uvx grippy-mcp in client configs
python -m grippy install-mcp --dev    # dev mode: uses uv run --directory

The installer detects Claude Code, Claude Desktop, and Cursor, then writes the server config with your chosen LLM transport and API keys.

Run the server directly:

python -m grippy serve

MCP tools return dense, structured JSON designed for AI agent consumption — no personality or ASCII art.

Configuration

Grippy is configured entirely through environment variables.

Cross-vendor model selection

If your codebase is co-developed with an AI coding assistant, we strongly recommend running Grippy on a model from a different vendor than the one that wrote the code. Different model families have different training data, different biases, and different blind spots. A reviewer that shares the same priors as the author is more likely to miss the same classes of bugs. Using a cross-vendor model — for example, reviewing GPT-authored code with Claude, or Claude-authored code with GPT — gives you a genuinely independent audit rather than an echo chamber.

Security profiles

Grippy ships with the deterministic rule engine on by default (security profile). Ten rules scan every diff for secrets, dangerous sinks, workflow permission escalation, path traversal, unsanitized LLM output, risky CI scripts, SQL injection, weak cryptography, hardcoded credentials, and insecure deserialization — before the LLM sees anything. These findings are guaranteed, not hallucinated.

Switch profiles via GRIPPY_PROFILE env var or --profile CLI flag (CLI takes priority).

# Use the default (security)
grippy

# Explicit profile
grippy --profile strict-security

# Via environment variable
GRIPPY_PROFILE=general grippy

The 10 deterministic rules:

Rule findings are injected into the LLM context as confirmed facts for explanation.

When the knowledge graph is available (CI with caching, or MCP with persistent GRIPPY_DATA_DIR), rule findings are enriched with:

• Blast radius — how many modules depend on the flagged file

• Recurrence — whether this rule has fired on this file in prior reviews

• False positive suppression — import-aware suppression (e.g., SQL injection suppressed when file imports SQLAlchemy)

• Finding velocity — how often this rule fires across recent reviews

Suppression

.grippyignore — file-level suppression

Create a .grippyignore file in your repo root to exclude files from review. Uses gitignore syntax (comments, negation, wildcards):

# Exclude generated code
vendor/
*.generated.py

# Exclude test fixtures that contain intentional anti-patterns
tests/test_rule_*.py

# But keep the hostile environment tests
!tests/test_hostile_environment.py

Excluded files are stripped from the diff before either the rule engine or the LLM sees them.

# nogrip — line-level pragma

Suppress deterministic rule findings on specific lines:

password = os.environ["DB_PASS"]  # nogrip
conn = f"postgres://{user}:{password}@host/db"  # nogrip: hardcoded-credentials
h = hashlib.md5(data)  # nogrip: weak-crypto, hardcoded-credentials

• Bare # nogrip suppresses all rules on that line

• # nogrip: rule-id suppresses only the named rule

• # nogrip: id1, id2 suppresses multiple rules

• Rules only — the LLM reviewer still sees the line and may comment on it

Review modes

GitHub Actions outputs

When running as a GitHub Action, Grippy sets these step outputs for downstream workflow logic:

Security

Grippy operates in an adversarial environment — PR diffs are untrusted input controlled by any contributor. Defense-in-depth sanitization is applied at every stage of the pipeline, validated by a 44-test adversarial test suite covering 9 attack domains.

Input sanitization. All untrusted text (PR metadata, diffs, tool outputs) passes through navi-sanitize for Unicode normalization — stripping invisible characters (ZWSP, bidi overrides, variation selectors), normalizing homoglyphs (Cyrillic/Greek → ASCII), and removing null bytes. This runs before any other processing.

Prompt injection defense. Three layers protect the LLM context:

1. XML escaping — All context sections (<diff>, <pr_metadata>, <rule_findings>, etc.) are XML-escaped, preventing </diff><system>... breakout attacks.

2. NL injection pattern neutralization — Seven compiled regex patterns detect and replace natural-language injection attempts (scoring directives, confidence manipulation, system override phrases) with [BLOCKED] markers.

3. Data-fence boundary — A preamble in the LLM prompt explicitly marks all subsequent content as "USER-PROVIDED DATA only" with instructions to ignore embedded directives.

Output sanitization. LLM-generated text passes through a five-stage pipeline before posting to GitHub:

1. navi-sanitize — Unicode normalization (same as input stage).

2. nh3 — Rust-based HTML sanitizer strips all HTML tags from free-text fields.

3. Markdown image stripping — Removes ![](url) syntax to prevent tracking pixels in review comments.

4. Markdown link rewriting — Converts [text](https://url) to plain text to prevent phishing links.

5. URL scheme filter — Removes javascript:, data:, and vbscript: schemes from remaining link syntax.

Tool output sanitization. Codebase tool responses (read_file, grep_code, list_files) are sanitized with navi-sanitize and XML-escaped before reaching the LLM, preventing indirect prompt injection through crafted file contents.

Adversarial test suite. tests/test_hostile_environment.py exercises 44 attack scenarios across Unicode attacks, prompt injection, tool exploitation, output sanitization gaps, information leakage, schema validation attacks, session history poisoning, and more. All 44 pass.

See the Security Model for codebase tool protections, CI hardening, and the full threat model.

Retrieval Quality Benchmarks

Grippy includes a benchmark suite for validating search and graph retrieval quality.

# Run search benchmarks (requires embedding model)
python -m benchmarks search --k 5

# Run graph retrieval benchmarks (requires populated graph DB)
python -m benchmarks graph

# Run all benchmarks
python -m benchmarks all

Results are written as JSON to benchmarks/output/.

Documentation

• Getting Started — Setup for OpenAI, local LLMs, and development

• Configuration — Environment variables and model options

• Architecture — Module map, prompt system, data flow

• Review Modes — The 6 review modes and how they work

• Scoring Rubric — How Grippy scores PRs

• Security Model — Codebase tool protections, hardened CI

• Self-Hosted LLM Guide — Ollama/LM Studio + Cloudflare Tunnel

• Contributing — Dev setup, testing, conventions

• Examples — Copy-paste workflow YAMLs and sample review output

• Changelog — Release history

License

MIT