# Runkids AI Hooks Integration AI Hooks Integration

> AI Hooks Integration

- Skill: `tomevault-io/runkids-ai-hooks-integration-ai-hooks-integration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/runkids-ai-hooks-integration-ai-hooks-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/runkids-ai-hooks-integration-ai-hooks-integration/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/runkids-ai-hooks-integration-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

```bash
# 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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/runkids) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->