Gemini CLI Hooks Pack: 10 Ready Hooks + Linter + Simulator

10 tested hooks for Google's Gemini CLI, plus an installer that merges them into .gemini/settings.json, a simulator that runs any hook the way Gemini CLI does and checks its output contract, and a linter that catches the mistakes that make hooks silently never fire. Python 3.9+, standard library only, works offline. Linux, macOS, WSL.

Profiles: balanced (default, first 7), strict (all 10), guardrails (first 5, no lifecycle hooks), logging (audit, context, notes, notify). Ready-made templates/settings.<profile>.json are included if you prefer to copy by hand.

python3 tools/install.py /path/to/repo                       # balanced profile into .gemini/settings.json
python3 tools/install.py /path/to/repo --profile strict
python3 tools/install.py /path/to/repo --only block-dangerous-shell,protect-files
python3 tools/install.py --user --profile guardrails          # ~/.gemini for every project
python3 tools/install.py /path/to/repo --dry-run              # show the merged settings.json, change nothing

The installer copies the scripts to .gemini/hooks/, merges hooks by name (your own hooks and other settings are kept, re-running is safe), writes settings.json.bak, and never overwrites an edited hooks-config.json. Gemini CLI fingerprints project hooks: on the next start it warns you about the new hooks; review them, then check /hooks panel. Turn one off with /hooks disable <name> or add the name to hooks.disabled.

Edit .gemini/hooks/hooks-config.json: protected_paths, protected_branches, mcp_allow / mcp_deny, test_command (empty = auto-detect npm test, pytest or unittest, go test ./..., cargo test), test_timeout, context_limit_chars, log paths, desktop_notifications.

python3 tools/simulate.py hooks/block_dangerous_shell.py BeforeTool --tool run_shell_command --command "git push -f origin main"
python3 tools/simulate.py my_hook.py AfterAgent --prompt "fix it" --stop-hook-active
python3 tools/simulate.py my_hook.py BeforeTool --event event.json --json

It prints the decision Gemini CLI would take and flags contract problems: text before the JSON on stdout (Gemini then ignores your deny and shows the text as a message), deny without a reason, decisions on advisory events, exit codes that only warn.

python3 tools/gemini_hooks_lint.py .gemini/settings.json ~/.gemini/settings.json   # exit 1 on errors, --json available

Checks: unknown events (Claude Code names like PreToolUse), Claude tool names (Bash, Write) and mcp__server__tool matchers, invalid regexes, regex matchers on lifecycle events (they are exact strings), bad SessionStart / PreCompress values, missing hooks arrays, type other than command, timeouts given in seconds (Gemini uses milliseconds), duplicate names, relative script paths, missing scripts, secrets in commands, and stale hooks.disabled entries.

./tools/demo.sh      # simulate hooks, lint examples/broken, install into a temp repo and lint it
./run_tests.sh       # 24 unit tests, offline

docs/events.md is a one-page reference of all 11 events, their matchers and what each output field does.

• Pattern-based guards reduce risk; they are not a sandbox. Keep Gemini CLI's own approval mode and sandboxing on.
• Built against Gemini CLI's hooks documentation as of November 2026. If Google changes the hook contract, re-run the linter and simulator.
• require-tests runs your test suite after each agent turn that changed code; set test_command to something fast.
• Not affiliated with Google. "Gemini" is a trademark of Google LLC.