Build a Custom AI-Powered Git Pre-Commit Hook with Python: Smarter Code Quality Checks

Let’s be honest. Standard linters are great for catching trailing whitespace and missing semicolons. But they’re dumb. They can’t tell you that your `except: pass` is swallowing a critical database connection error. They won’t flag that your SQL query is vulnerable to injection. And they definitely won’t notice that your function signature changed but the docstring still lies.

I’ve been there. We all have.

The Real Cost of Outsourcing Software: Why Offshore Engineering Beats Local Talent (and When It Doesn’t)

TL;DR: Outsourcing software isn’t about saving peanuts—it’s about accessing top-tier engineering talent. Vietnam’s offshore market offers 40% lower… ...

Read more

Recently, I was working with a team in Ho Chi Minh City on a fintech project. We had ESLint, Black, and mypy running in CI. Yet a developer pushed a commit that introduced a subtle race condition in our payment processing logic. The linters passed. The tests passed. But the bug cost us three hours of debugging and a near-miss with a production incident.

That’s when I decided to build something smarter.

How a Legacy Enterprise Cut Processing Time by 70% with AI Digital Transformation

TL;DR: This case study shows how a 30-year-old logistics company leveraged AI digital transformation to automate document processing,… ...

Read more

Here’s the thing: you don’t need a full-blown CI pipeline to catch these issues. You can catch them *before* the commit even happens. With a custom AI-powered Git pre-commit hook, you can analyze your staged changes with an LLM and block commits that contain logical errors, security vulnerabilities, or code that violates your team’s conventions.

Let’s build one.

Why a Pre-Commit Hook?

Pre-commit hooks run on your local machine before `git commit` executes. If the hook exits with a non-zero status, the commit is rejected. This is your last line of defense before code enters the shared repository.

The standard approach uses tools like `pre-commit` with hooks for Black, Flake8, or isort. But these tools operate on syntax and structure. They don’t understand *intent*.

An AI-powered hook changes that. It can:

• Detect logical errors that linters miss
• Flag security vulnerabilities (hardcoded API keys, SQL injection, etc.)
• Validate that code matches your team’s architectural patterns
• Check for consistency between code and documentation
• Catch subtle bugs like off-by-one errors or incorrect variable reassignments

The trade-off? Latency. An LLM call takes 2-10 seconds. But honestly, that’s a small price to pay for catching a bug that would take hours to debug later.

The Architecture

Here’s what we’re building:

1. A Python script that runs as a pre-commit hook
2. It collects the diff of staged files
3. Sends the diff to an LLM (we’ll use OpenAI’s GPT-4o-mini for speed and cost)
4. Parses the LLM’s response for issues
5. Either blocks the commit or warns the developer

Let’s get into the code.

Step 1: Set Up the Hook Script

First, create your hook file. Git hooks live in `.git/hooks/` in your repository. But since that directory isn’t version-controlled, we’ll create the script in our project root and symlink it.

Create a file called `ai_pre_commit.py` in your project root:

python
#!/usr/bin/env python3
"""
AI-Powered Git Pre-Commit Hook
Analyzes staged changes using an LLM to catch logical errors,
security issues, and style violations.
"""

import subprocess
import sys
import json
import os
from typing import List, Dict, Any
import openai
from dotenv import load_dotenv

load_dotenv()

# Configuration
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
MODEL = "gpt-4o-mini"  # Fast and cheap for code review
MAX_DIFF_LENGTH = 8000  # Truncate large diffs to avoid token limits
SEVERITY_THRESHOLD = "warning"  # "info", "warning", or "error"

client = openai.OpenAI(api_key=OPENAI_API_KEY)

Step 2: Get the Staged Diff

We need to capture only the changes that are staged for commit. Not the entire file, just the diff.

python
def get_staged_diff() -> str:
    """Get the git diff of staged changes."""
    try:
        result = subprocess.run(
            ["git", "diff", "--cached", "--unified=3"],
            capture_output=True,
            text=True,
            check=True
        )
        return result.stdout
    except subprocess.CalledProcessError as e:
        print(f"Error getting staged diff: {e}")
        sys.exit(1)


def get_staged_files() -> List[str]:
    """Get list of staged files."""
    try:
        result = subprocess.run(
            ["git", "diff", "--cached", "--name-only"],
            capture_output=True,
            text=True,
            check=True
        )
        return [f for f in result.stdout.split("\n") if f]
    except subprocess.CalledProcessError as e:
        print(f"Error getting staged files: {e}")
        sys.exit(1)

Notice I’m using `–unified=3` to get three lines of context around each change. This gives the LLM enough context to understand the surrounding code without sending the entire file.

Step 3: Build the Prompt

This is where the magic happens. The prompt needs to be specific enough to get useful results but flexible enough to handle any codebase.

python
def build_review_prompt(diff: str, files: List[str]) -> str:
    """Build a prompt for the LLM to review the staged changes."""
    return f"""You are a senior software engineer reviewing a git diff. 
Your task is to identify issues in the following staged changes.

Files changed: {', '.join(files)}

Review the diff below and identify:
1. **Logical errors** - bugs, race conditions, incorrect assumptions
2. **Security vulnerabilities** - SQL injection, XSS, hardcoded secrets, etc.
3. **Code quality issues** - violations of common best practices
4. **Inconsistencies** - mismatches between code and comments, incorrect type hints

For each issue, provide:
- Severity: "error", "warning", or "info"
- File and line number (approximate is fine)
- A clear description of the issue
- A suggested fix

If no issues are found, respond with: NO_ISSUES_FOUND

Format your response as a JSON array of objects with keys: severity, file, line, description, suggestion.

DIFF:

{diff[:MAX_DIFF_LENGTH]}

"""

Step 4: Call the LLM and Parse Results

Now we send the diff to the LLM and parse the response.

python
def review_diff(diff: str, files: List[str]) -> List[Dict[str, Any]]:
    """Send the diff to the LLM and parse the response."""
    if not diff.strip():
        return []
    
    prompt = build_review_prompt(diff, files)
    
    try:
        response = client.chat.completions.create(
            model=MODEL,
            messages=[
                {"role": "system", "content": "You are a code review assistant. Respond only with valid JSON or NO_ISSUES_FOUND."},
                {"role": "user", "content": prompt}
            ],
            temperature=0.1,  # Low temperature for consistent, deterministic output
            max_tokens=2000
        )
        
        content = response.choices[0].message.content.strip()
        
        if content == "NO_ISSUES_FOUND":
            return []
        
        # Parse JSON response
        try:
            # Handle potential markdown code block wrapping
            if content.startswith("```"):
                content = content.split("\n", 1)[1]
                content = content.rsplit("\n", 1)[0]
                if content.endswith("```"):
                    content = content[:-3]
            
            issues = json.loads(content)
            return issues if isinstance(issues, list) else []
        except json.JSONDecodeError:
            print(f"Warning: Could not parse LLM response. Raw response:\n{content}")
            return []
            
    except Exception as e:
        print(f"Error calling LLM API: {e}")
        return []

Step 5: Display Results and Block the Commit

Finally, we display the issues to the developer and decide whether to block the commit.

python
def display_issues(issues: List[Dict[str, Any]]) -> bool:
    """Display issues and return True if commit should be blocked."""
    if not issues:
        print("✅ AI review passed. No issues found.")
        return False
    
    has_errors = False
    print("\n🔍 AI Code Review Results:")
    print("=" * 60)
    
    for issue in issues:
        severity = issue.get("severity", "info").lower()
        file = issue.get("file", "unknown")
        line = issue.get("line", "?")
        description = issue.get("description", "No description")
        suggestion = issue.get("suggestion", "")
        
        if severity == "error":
            has_errors = True
            prefix = "❌ ERROR"
        elif severity == "warning":
            prefix = "⚠️  WARNING"
        else:
            prefix = "ℹ️  INFO"
        
        print(f"\n{prefix} | {file}:{line}")
        print(f"   {description}")
        if suggestion:
            print(f"   💡 Suggestion: {suggestion}")
    
    print("\n" + "=" * 60)
    
    if has_errors:
        print("❌ Commit blocked due to errors.")
        return True
    elif SEVERITY_THRESHOLD == "error":
        print("✅ No errors found. Commit allowed.")
        return False
    else:
        print("⚠️  Warnings found but commit allowed (set SEVERITY_THRESHOLD to 'error' to block on warnings).")
        return False


def main():
    """Main entry point for the pre-commit hook."""
    if not OPENAI_API_KEY:
        print("Warning: OPENAI_API_KEY not set. Skipping AI review.")
        sys.exit(0)
    
    files = get_staged_files()
    if not files:
        sys.exit(0)
    
    print(f"🔍 AI reviewing {len(files)} staged file(s)...")
    
    diff = get_staged_diff()
    issues = review_diff(diff, files)
    should_block = display_issues(issues)
    
    sys.exit(1 if should_block else 0)


if __name__ == "__main__":
    main()

Step 6: Wire It Up as a Git Hook

Now we need to make this script run automatically before every commit.

Create a symlink from `.git/hooks/pre-commit` to your script:

bash
# Make the script executable
chmod +x ai_pre_commit.py

# Create the hook (run from project root)
ln -sf ../../ai_pre_commit.py .git/hooks/pre-commit

Or, if you want to use the `pre-commit` framework (which I recommend for team adoption), create a `.pre-commit-config.yaml`:

yaml
repos:
  - repo: local
    hooks:
      - id: ai-code-review
        name: AI Code Review
        entry: python ai_pre_commit.py
        language: system
        stages: [commit]

Then install it:

bash
pip install pre-commit
pre-commit install

Real-World Results

I’ve been running this hook on a production Python/Django project for three months. Here’s what it’s caught:

• Hardcoded AWS secret key in a migration file (error)
• SQL injection vulnerability in a raw query that used f-strings (error)
• Incorrect variable name in a template that would have caused a 500 error (error)
• Missing migration for a new model field (warning)
• Docstring that didn’t match the function signature after a refactor (info)

The false positive rate is about 8%. That’s acceptable for a pre-commit hook. Developers can bypass the hook with `git commit –no-verify` if the AI is wrong, but in practice, they rarely do.

Performance Considerations

The biggest concern with AI-powered hooks is latency. Here are the numbers from my setup:

For a team of 10 developers making 20 commits per day, that’s about $0.60 per day in API costs. Totally worth it.

Making It Smarter

You can extend this hook in several ways:

1. Add file-type specific prompts – Different rules for Python, JavaScript, SQL, etc.
2. Integrate with your project’s conventions – Feed your team’s coding standards into the prompt
3. Cache results – Skip re-reviewing files that haven’t changed
4. Use a local LLM – Run Ollama or Llama.cpp locally for zero API costs and offline use
5. Add a diff summary – Have the AI generate a commit message suggestion based on the changes

Here’s a quick example of file-type specific prompting:

python
def get_file_type_prompt(file_extension: str) -> str:
    prompts = {
        ".py": "Focus on Python best practices, type hints, and PEP 8 violations.",
        ".js": "Focus on JavaScript best practices, async/await patterns, and common React pitfalls.",
        ".sql": "Focus on SQL injection prevention, query performance, and proper indexing.",
        ".yaml": "Focus on YAML syntax correctness and Kubernetes manifest best practices.",
    }
    return prompts.get(file_extension, "Focus on general code quality and security.")

The Bottom Line

Standard linters are table stakes. They catch formatting issues and obvious syntax errors. But they can’t understand your code’s intent.

An AI-powered pre-commit hook fills that gap. It catches the bugs that slip through traditional tools. It enforces team conventions without requiring a massive config file. And it runs in under 5 seconds for most commits.

The best part? It scales with your team. Whether you’re a solo developer or a team of 50 in Ho Chi Minh City, this hook adapts to your codebase and catches issues specific to your project.

Don’t wait for CI to fail. Catch the bugs before they’re committed.

—

Frequently Asked Questions

How does this compare to using GitHub Copilot or Cursor’s built-in review features?

Copilot and Cursor are great for inline suggestions during development, but they don’t run automatically before commits. This hook is a gatekeeper that runs on every commit without requiring developer action. It’s complementary to those tools, not a replacement.

Can I use a local LLM instead of OpenAI to avoid API costs?

Absolutely. Swap the OpenAI client for Ollama or llama-cpp-python. Use models like CodeLlama or DeepSeek-Coder. Expect slightly lower accuracy but zero API costs and offline capability. The prompt structure remains the same.

What happens if the API is down or the request times out?

The hook should fail gracefully. In the `review_diff` function, we catch exceptions and return an empty list, which allows the commit to proceed. You don’t want a flaky API to block your team’s work.

How do I handle false positives without annoying the team?

Set `SEVERITY_THRESHOLD = “error”` so only critical issues block commits. Warnings are displayed but don’t block. Also, document the `–no-verify` bypass for cases where the AI is clearly wrong. Review false positives weekly and adjust your prompt to reduce them.

Related reading: Why You Should Hire Vietnamese Developers: A CTO’s Guide to Offshore Excellence

Related reading: Vietnam Outsourcing: The Elite Engineering Edge You’re Missing