Ai Hooks Integration

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 ""
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 "" --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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: runkids
• Source: runkids/ai-hooks-integration
• License: MIT

Install and usage instructions live in the source repository linked above.