name: ai-hooks-integration
description: |
Integrate lifecycle hooks across AI coding tools (Claude Code, Gemini CLI, Cursor, OpenCode) and any CLI.
Use when: (1) installing/removing hooks, (2) creating OpenCode plugins, (3) setting up auto-formatting,
testing, notifications, security policies, (4) wrapping CLI tools without hooks API.
Triggers on: "add hook", "install hook", "hook integration", "PreToolUse", "PostToolUse",
"PermissionRequest", "PostToolUseFailure", "SubagentStart", "SubagentStop", "TeammateIdle",
"TaskCompleted", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "PreCompact",
"beforeShellExecution", "auto-format", "notify on complete", "wrap CLI", "intercept command",
"HTTP hook", "prompt hook", "agent hook", "async hook".
AI Hooks Integration
Decision Tree
Does the target tool have a hooks API?
├── YES (Claude, Gemini CLI, Cursor, OpenCode)
│ └── Installing hooks for multiple tools at once?
│ ├── YES → Use install_all.py
│ │ └── Need cross-tool source detection?
│ │ ├── YES → --unified mode (recommended)
│ │ └── NO → --command mode (classic)
│ └── NO → Use single-tool scripts
│ ├── Claude/Gemini/Cursor → merge_hooks.py
│ └── OpenCode → install_opencode_plugin.py
└── NO (gh, aws, kubectl, docker, etc.)
└── Use install_cli_wrapper.py
Quick Commands
# Multi-tool: Unified mode (recommended)
scripts/install_all.py --unified --handler "/path/to/handler" --name my-hook
# Multi-tool: Classic mode
scripts/install_all.py --command "/path/to/hook" --name my-hook
# Single tool
scripts/merge_hooks.py --tool claude --path ~/.claude/settings.json --command "<hook>"
scripts/install_opencode_plugin.py --name my-hook --output ~/.config/opencode/plugins
# CLI without hooks API
scripts/install_cli_wrapper.py --cli gh --hook "/path/to/hook"
# Remove
scripts/remove_all.py --command "<hook>" --plugin ~/.config/opencode/plugins/my-hook.js
scripts/remove_cli_wrapper.py --cli gh
# Preview
--dry-run # Add to any command
Mode Comparison
| Mode |
When to Use |
Source Detection |
Event Filtering |
| Unified |
Multiple AI tools share config files |
Auto (process tree) |
Yes |
| Classic |
Single tool or explicit routing |
Manual (--source flag) |
No |
| CLI Wrapper |
Tools without hooks API |
N/A |
N/A |
Tool Support
| Tool |
Config |
Events |
Hook Types |
Has Hooks API |
| Claude |
~/.claude/settings.json |
17 events |
command, http, prompt, agent |
Yes |
| Gemini CLI |
~/.gemini/settings.json |
11 events |
command |
Yes |
| Cursor |
~/.cursor/hooks.json |
3 events |
command |
Yes |
| OpenCode |
~/.config/opencode/plugins/*.js |
10 events |
ES module |
Yes (plugin) |
| Gemini IDE |
N/A |
N/A |
N/A |
No |
| gh, aws, etc. |
N/A |
N/A |
N/A |
No → Use wrapper |
Claude Code Events (17 total)
SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure,
Notification, SubagentStart, SubagentStop, Stop, TeammateIdle, TaskCompleted, ConfigChange,
WorktreeCreate, WorktreeRemove, PreCompact, SessionEnd
Gemini CLI Events (11 total)
SessionStart, SessionEnd, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification
References
| File |
When to Read |
references/tool-reference.md |
Config paths, events, payload formats, templates |
references/use-cases.md |
Hook patterns: security, formatting, testing, notifications |
references/unified-hook-usage.md |
Cross-tool interference, source detection, debug |
Key Behaviors
- Idempotent: Duplicates skipped, safe to re-run
- Safe merge: Only adds; never overwrites existing hooks
- Debug:
HOOK_DEBUG=1 enables logging
By