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
1---2name: ai-hooks-integration3description: 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".4---56# AI Hooks Integration78## Decision Tree910```11Does the target tool have a hooks API?12├── YES (Claude, Gemini CLI, Cursor, OpenCode)13│ └── Installing hooks for multiple tools at once?14│ ├── YES → Use install_all.py15│ │ └── Need cross-tool source detection?16│ │ ├── YES → --unified mode (recommended)17│ │ └── NO → --command mode (classic)18│ └── NO → Use single-tool scripts19│ ├── Claude/Gemini/Cursor → merge_hooks.py20│ └── OpenCode → install_opencode_plugin.py21└── NO (gh, aws, kubectl, docker, etc.)22 └── Use install_cli_wrapper.py23```2425## Quick Commands2627```bash28# Multi-tool: Unified mode (recommended)29scripts/install_all.py --unified --handler "/path/to/handler" --name my-hook3031# Multi-tool: Classic mode32scripts/install_all.py --command "/path/to/hook" --name my-hook3334# Single tool35scripts/merge_hooks.py --tool claude --path ~/.claude/settings.json --command "<hook>"36scripts/install_opencode_plugin.py --name my-hook --output ~/.config/opencode/plugins3738# CLI without hooks API39scripts/install_cli_wrapper.py --cli gh --hook "/path/to/hook"4041# Remove42scripts/remove_all.py --command "<hook>" --plugin ~/.config/opencode/plugins/my-hook.js43scripts/remove_cli_wrapper.py --cli gh4445# Preview46--dry-run # Add to any command47```4849## Mode Comparison5051| Mode | When to Use | Source Detection | Event Filtering |52|------|-------------|------------------|-----------------|53| **Unified** | Multiple AI tools share config files | Auto (process tree) | Yes |54| **Classic** | Single tool or explicit routing | Manual (--source flag) | No |55| **CLI Wrapper** | Tools without hooks API | N/A | N/A |5657## Tool Support5859| Tool | Config | Events | Hook Types | Has Hooks API |60|------|--------|--------|------------|---------------|61| Claude | `~/.claude/settings.json` | 17 events | command, http, prompt, agent | Yes |62| Gemini CLI | `~/.gemini/settings.json` | 11 events | command | Yes |63| Cursor | `~/.cursor/hooks.json` | 3 events | command | Yes |64| OpenCode | `~/.config/opencode/plugins/*.js` | 10 events | ES module | Yes (plugin) |65| Gemini IDE | N/A | N/A | N/A | **No** |66| gh, aws, etc. | N/A | N/A | N/A | **No** → Use wrapper |6768### Claude Code Events (17 total)6970SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure,71Notification, SubagentStart, SubagentStop, Stop, TeammateIdle, TaskCompleted, ConfigChange,72WorktreeCreate, WorktreeRemove, PreCompact, SessionEnd7374### Gemini CLI Events (11 total)7576SessionStart, SessionEnd, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification7778## References7980| File | When to Read |81|------|--------------|82| `references/tool-reference.md` | Config paths, events, payload formats, templates |83| `references/use-cases.md` | Hook patterns: security, formatting, testing, notifications |84| `references/unified-hook-usage.md` | Cross-tool interference, source detection, debug |8586## Key Behaviors8788- **Idempotent**: Duplicates skipped, safe to re-run89- **Safe merge**: Only adds; never overwrites existing hooks90- **Debug**: `HOOK_DEBUG=1` enables logging
runkids