Pre-commit Hook¶

AI Guardian can scan staged files for secrets before they are committed to your repository. This provides a last line of defense against accidentally committing sensitive data.

Quick Start¶

ai-guardian setup --pre-commit

This auto-detects whether the pre-commit framework is installed and chooses the best method:

pre-commit framework available: installs .pre-commit-config.yaml and runs pre-commit install
No framework: installs a standalone git hook at .git/hooks/pre-commit

Installation Methods¶

Method 1: `ai-guardian setup --pre-commit` (Recommended)¶

The setup command handles detection and installation automatically:

# Install pre-commit hook
ai-guardian setup --pre-commit

# Preview what would be installed (no changes)
ai-guardian setup --pre-commit --dry-run

# Remove AI Guardian pre-commit hooks
ai-guardian setup --pre-commit --uninstall-hooks

Method 2: Direct Git Hook¶

Manually install a git hook that calls ai-guardian scan on staged files:

cat > .git/hooks/pre-commit << 'HOOK'
#!/bin/bash
# AI Guardian pre-commit hook
# Scans staged files for secrets before commit

set -e

echo "🛡️ AI Guardian: Scanning staged files for secrets..."

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR)

if [ -z "$STAGED_FILES" ]; then
  echo "✓ No files staged for commit"
  exit 0
fi

TEMP_DIR=$(mktemp -d)
trap "rm -rf $TEMP_DIR" EXIT

echo "$STAGED_FILES" | while IFS= read -r file; do
  if [ -z "$file" ]; then continue; fi
  mkdir -p "$TEMP_DIR/$(dirname "$file")"
  git show ":$file" > "$TEMP_DIR/$file" 2>/dev/null || true
done

if gitleaks detect \
    --source "$TEMP_DIR" \
    --no-git \
    --redact \
    --verbose \
    --exit-code 42; then
  echo "✓ No secrets detected in staged files"
  exit 0
else
  EXIT_CODE=$?
  if [ $EXIT_CODE -eq 42 ]; then
    echo ""
    echo "❌ COMMIT BLOCKED: Secrets detected in staged files"
    echo "Please remove sensitive information and try again."
    exit 1
  else
    echo "⚠️ Gitleaks scan failed (exit code: $EXIT_CODE)"
    echo "Allowing commit to proceed (fail-open policy)"
    exit 0
  fi
fi
HOOK

chmod +x .git/hooks/pre-commit

Method 3: pre-commit Framework¶

If you use the pre-commit framework:

pip install pre-commit

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks
        name: Detect secrets with gitleaks
        entry: gitleaks detect --no-git --redact --verbose --exit-code 42
        language: golang
        stages: [commit]
        pass_filenames: false

Then install:

pre-commit install

Protection Scope¶

The pre-commit hook scans at commit time, not during AI generation:

What it does	What it does NOT do
Blocks commits containing secrets	Scan prompts during AI interaction
Prevents secrets in git history	Prevent AI from seeing secrets in the working directory
Works with any IDE or CLI workflow	Replace real-time IDE hooks

For real-time protection during AI interactions, use ai-guardian setup --ide claude (or --ide cursor, --ide copilot). The pre-commit hook is a complementary layer.

Uninstalling¶

# Automatic removal
ai-guardian setup --pre-commit --uninstall-hooks

# Manual removal (direct git hook)
rm .git/hooks/pre-commit

# Manual removal (pre-commit framework)
# Remove the gitleaks entry from .pre-commit-config.yaml

Configuration¶

Fail Policy¶

The default behavior is fail-open: if the scanner encounters an error (not a secret detection), the commit proceeds. To change to fail-closed, edit the hook script and replace the fallback exit 0 with exit 1.

Gitleaks Rules¶

Customize detection with .gitleaks.toml in your project root:

[allowlist]
  description = "Allow test secrets"
  paths = [
    '''tests/fixtures/.*''',
  ]

See Gitleaks documentation for the full configuration reference.

Skipping the Hook¶

To bypass the hook for a single commit:

git commit --no-verify

Aider Integration¶

For Aider users, enable commit verification in .aider.conf.yml:

git-commit-verify: true

See docs/AIDER.md for detailed Aider integration instructions.

Troubleshooting¶

Hook not running: Verify the hook is executable (chmod +x .git/hooks/pre-commit) and that Aider has git-commit-verify: true if applicable.

Scanner not found: Install a scanner engine first (ai-guardian setup --install-scanner).

False positives: Add allowlist rules to .gitleaks.toml or use inline # gitleaks:allow comments.