diff --git a/README.md b/README.md
index aa6f1e1..aecd5b4 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@ cd opencode-devbox
 cp .env.example .env
 # Edit .env with your provider, API key, workspace path, git config
 
-# Install git hooks (secret scanning) before committing
+# Activate the tracked git hooks (secret scanning) before committing
 brew install gitleaks  # macOS / Linuxbrew
 ./setup-hooks.sh
 
diff --git a/hooks/pre-commit b/hooks/pre-commit
new file mode 100755
index 0000000..5f8163a
--- /dev/null
+++ b/hooks/pre-commit
@@ -0,0 +1,26 @@
+#!/bin/bash
+# Pre-commit hook — scans staged files for secrets using gitleaks
+
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo ""
+  echo "⚠️  gitleaks is not installed — skipping secret scan"
+  echo "   Install: brew install gitleaks  (macOS)"
+  echo "   Or: curl -sSL https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks_\$(uname -s)_\$(uname -m).tar.gz | sudo tar -xz -C /usr/local/bin gitleaks"
+  echo ""
+  exit 0
+fi
+
+echo "🔒 Scanning for secrets..."
+
+if gitleaks protect --staged --no-banner 2>/dev/null; then
+  echo "✅ No secrets detected"
+  exit 0
+else
+  echo ""
+  echo "❌ Secrets detected in staged changes — commit blocked"
+  echo ""
+  echo "   Details:  gitleaks protect --staged --verbose"
+  echo "   Bypass:   git commit --no-verify"
+  echo ""
+  exit 1
+fi