mastiff 0.1.0

AI code review agent that detects dangerous patterns in LLM-generated code

Mastiff

AI code review agent that detects dangerous patterns in LLM-generated code.

Mastiff analyzes git diffs using the Claude API to detect production-risk patterns across four categories — blocking/deadlocks, race conditions, performance degradation, and resource leaks — scoring each finding by severity and confidence.

Why Mastiff?

LLM-generated code often looks correct at first glance but can contain subtle patterns that only manifest in production:

• Event loop blocking — synchronous calls in async contexts that freeze the application
• Race conditions — shared mutable state accessed without proper synchronization
• O(n²) algorithms — nested loops and unbounded queries that degrade with scale
• Resource leaks — file handles, connections, and sockets opened but never closed

Traditional linters catch syntax and style issues. Mastiff focuses specifically on the patterns LLMs tend to introduce — not to replace linters, but to complement them with production-risk awareness.

What It Detects

Category	Description	Examples
Blocking/Deadlock	Synchronous blocking calls in async contexts, potential deadlocks	time.sleep() in async, synchronous I/O in event loop, inconsistent lock ordering
Race Condition	Shared mutable state without synchronization, TOCTOU	Global variable from multiple threads without locks, non-atomic read-modify-write
Degradation	O(n²) algorithms, excessive allocations, unbounded growth	Nested loops, loading entire DB table into memory, missing pagination
Resource Leak	Resources opened but not properly closed	open() without context manager, DB connection not returned to pool

Quick Start

pip install mastiff
export ANTHROPIC_API_KEY="sk-ant-..."
mastiff review --staged

Alternative installation methods:

pipx install mastiff
# or
uv tool install mastiff

Get your API key at https://console.anthropic.com/

Output Example

Terminal (default):

                    Review Findings
┏━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ File         ┃ Line ┃ Severity ┃ Category      ┃ Title                      ┃ Confidence ┃
┡━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ api/users.py │ 42   │ critical │ blocking      │ time.sleep in async handler │ 92%        │
│ db/pool.py   │ 15   │ warning  │ resource_leak │ Connection not returned     │ 78%        │
└──────────────┴──────┴──────────┴───────────────┴────────────────────────────┴────────────┘

JSON (--format json):

{
  "findings": [
    {
      "rule_id": "blocking-sync-sleep",
      "category": "blocking",
      "severity": "critical",
      "file_path": "api/users.py",
      "line_start": 42,
      "title": "time.sleep in async handler",
      "confidence": 0.92
    }
  ]
}

Usage

CLI

# Review staged changes
mastiff review --staged

# Review a commit range
mastiff review HEAD~3..HEAD

# Choose review depth
mastiff review --staged --profile quick

# JSON output
mastiff review --staged --format json

# Strict mode: exit 1 on any finding
mastiff review --staged --strict

Review profiles:

Profile	Diff budget	Context budget	Use case
quick	5,000 tokens	3,000 tokens	Pre-commit, editor saves
standard	20,000 tokens	15,000 tokens	PR review (default)
deep	50,000 tokens	30,000 tokens	Release audits

Pre-commit Hook

# Install the pre-commit hook
mastiff install

# Commits are automatically reviewed
git commit -m "feat: add user endpoint"
# → mastiff reviews staged changes

In CI environments (CI=true), the hook runs in strict mode and blocks on any finding. When a baseline exists, only new findings are reported.

LSP Server (Experimental)

mastiff server

Provides real-time diagnostics on file save (quick profile). Configure your editor's LSP client to connect to mastiff.

With Claude Code

Mastiff is designed to review LLM-generated code. When using Claude Code as your development agent, Mastiff acts as an automated safety net that catches production-risk patterns before they reach your codebase.

Pre-commit hook (recommended):

Install the hook once and every commit Claude Code creates is automatically reviewed:

mastiff install

Claude Code commits through git, so the pre-commit hook runs transparently on every commit. Critical findings block the commit, giving you a chance to review before the code lands.

CI integration:

Add Mastiff to your CI pipeline to review every pull request that Claude Code opens:

# .github/workflows/ci.yml
- run: pip install mastiff
- run: mastiff review origin/main..HEAD --strict --format json

Manual review after a session:

After Claude Code completes a task in a worktree, review all changes before merging:

mastiff review main..HEAD --profile deep

Baseline

# Record current findings as baseline
mastiff baseline

# Only new findings are reported from now on

# Regenerate after refactoring
mastiff baseline --rebase

The baseline uses fingerprint-based stable IDs that are independent of line numbers, so minor code shifts don't invalidate existing suppressions.

Configuration

Generate a config file:

mastiff init

This creates mastiff.yaml with documented defaults. Key settings:

api:
  model: claude-opus-4-20250514      # Claude model to use

detection:
  min_confidence: 0.6           # Minimum confidence to report

security:
  never_send_paths:             # Files never sent to the API
    - .env
    - "*.pem"
    - "*.key"

cost:
  max_cost_usd_per_run: 1.00   # Per-run cost limit

All config models use Pydantic extra="forbid", so typos in config keys are caught immediately.

Security & Privacy

Mastiff sends code to the Claude API for analysis. Here is what it does to minimize exposure:

• What is sent: Only the diff is sent — never complete source files. Import tracing may include small fragments from related files, bounded by a token budget.
• Automatic redaction: Built-in regex patterns detect API keys, tokens, passwords, and private key headers. Detected values are replaced with [REDACTED] before sending. The Redactor also exposes Shannon entropy analysis for identifying high-entropy strings.
• File exclusion: The never_send_paths setting excludes sensitive file patterns (.env, *.pem, *.key, etc.) by default. These files are filtered out before any API call.
• Output sanitization: ANSI escape sequences and control characters are stripped from all output to prevent terminal injection.
• Prompt injection defense: User-supplied data (diffs, context) is wrapped in delimiter tags (<diff>, <context>) and the system prompt establishes reviewer-only behavior.

This is a best-effort approach to minimize sensitive data exposure. It does not guarantee that no secrets are sent. Review your never_send_paths configuration and consider the sensitivity of your codebase before use.

Cost Control

Approximate cost per review (depends on diff size and Claude API pricing):

Profile	Estimated cost
quick	~$0.01–0.05
standard	~$0.05–0.30
deep	~$0.10–0.50

The cost.max_cost_usd_per_run setting (default: $1.00) enforces a per-run budget.

Requirements

• Python >= 3.12
• Anthropic API key
• Git

Optional extras:

pip install "mastiff[tree-sitter]"  # Enhanced import tracing
pip install "mastiff[lsp]"          # LSP server support

Development

git clone <repo> && cd mastiff
uv sync --all-extras
pytest                 # 277 tests
ruff check .           # lint
mypy src/              # type check

Package structure:

src/mastiff/
├── _internal/       # Git and subprocess utilities
├── analysis/        # Categories, prompt building, LLM client
├── cli/             # Commands and terminal output
├── config/          # Schema, loader, defaults
├── context/         # Language parsers, import tracer, resolver
├── core/            # Engine, models, fingerprinting, severity
├── diff/            # Diff parsing, filtering, collection
├── integrations/    # Pre-commit hook, LSP server
├── observability/   # Logging and metrics
└── security/        # Secret patterns, redactor, sanitizer

License

MIT