diff-explainer

AI-powered git diff analysis: human-readable explanations, risk flags, and review checklists.

Works as a CLI, Python library, and MCP server tool.

Setup

pip install -r requirements.txt

# Optional: set for LLM-powered summaries
export OPENAI_API_KEY="sk-..."

Risk detection works without an API key. Only summaries and review checklists require the LLM.

Usage

CLI

# Pipe from git diff
git diff | python cli.py

# Read from file
python cli.py --file examples/sample.diff

# Auto-run git diff in current repo
python cli.py --git

# JSON output
python cli.py --file examples/sample.diff --format json

Python Library

from explainer import explain_diff

with open("changes.diff") as f:
    diff_text = f.read()

result = explain_diff(diff_text)
print(result.summary)
print(result.risk_flags)
print(result.files_changed)

MCP Server (opencode integration)

Add to your opencode.json:

{
  "mcpServers": {
    "diff-explainer": {
      "type": "stdio",
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/diff-explainer"
    }
  }
}

Available tools:

• explain_diff_tool(diff_text) — Explain any diff text
• explain_staged() — Explain currently staged git changes

Run standalone: python server.py

Features

• Hybrid analysis: Regex risk detection (offline) + LLM summaries (optional)
• 7 risk patterns: Removed error handling, changed timeouts, auth modifications, missing env defaults, large changes, tech debt markers, hardcoded secrets
• Graceful degradation: Works without API key — risk flags and file stats always available
• Multiple interfaces: CLI, library import, MCP server

Output Example

# Diff Explanation

## Summary
This change reduces retry resilience in the auth service and introduces a hardcoded API key.

**Category:** config_change

## Files Changed
- `src/auth.py` — +3/-7 lines
- `src/config.py` — +5/-1 lines

## Risk Flags
- 🔴 **HIGH**: Removed error handling code
- 🔴 **HIGH**: Modified auth/permission checks
- 🔴 **HIGH**: Possible hardcoded secret
- 🟡 **MEDIUM**: Changed retry/timeout values
- 🟢 **LOW**: Added TODO/FIXME/HACK comment

## Review Checklist
- [ ] Is removing the try/except intentional? What handles AuthError now?
- [ ] Why were retries reduced from 3 to 1?
- [ ] The hardcoded API key should be moved to a secrets manager.