captain-hook

🪝 captain-hook

The Universal Agent Skill & Claude Plugin for Navigating AI Coding Agent Hooks.

captain-hook is an open-source Agent Skill and Claude Plugin that equips AI agents and developers to command, write, scaffold, and configure native lifecycle hooks for 10+ major AI coding agents (Claude Code, Cursor, Windsurf, Aider, Antigravity, Continue CLI, Roo Code, OpenHands, Copilot, and Amazon Q).

---

⛵ Navigating the High Seas of AI Agent Hooks

• The Pain Point: Lifecycle hooks are a captain's most powerful weapon for deterministic security guardrails, command sandboxing, and quality gates in AI coding. However, unlike open skill standards, every AI coding agent uses completely different, constantly changing hook specifications, configuration schemas, JSON payload shapes, and exit code semantics.
• The Solution: captain-hook chart-maps all this fragmented information into one unified handbook, scaffolding library, and verification suite—saving developers and AI agents from drifting lost in the open sea of documentation for each individual agent.

---

⚓ Boarding the Ship (Installation & Setup)

1. Install as a Claude Plugin

Install captain-hook directly into Claude Code or compatible AI agent environments:

/plugin install shmulc8/captain-hook

2. Manual Clone & Local Verification

git clone https://github.com/shmulc8/captain-hook.git
cd captain-hook

# Run local hook verification suite before setting sail
./skills/captain-hook/scripts/verify_hooks.sh

---

🏴‍☠️ What Lies in the Treasure Chest

• 📚 Handbook & Guide (SKILL.md): Complete instructions on hook fundamentals, event lifecycles, stdin/stdout JSON contracts, and exit code blocking protocols (0 ALLOW, 2 BLOCK).
• 🧭 Exhaustive 10-Agent Specifications (references/specs/): Self-contained, live-verified specification guides cross-referenced with official documentation.
• 🗡️ Production Hook Recipes (references/recipes.md): Copy-pasteable standalone Python, Bash, and Node.js hook scripts for Secret Scanning, Command Sandboxing, Symlink Guards, Auto-Formatting, and Test Gates.
• 📄 Scaffolding Templates (examples/): Valid starter configuration files for .cursor/hooks.json, .windsurf/hooks.json, .claude/settings.json, .aider.conf.yml, and hooks/prevent.py.
• 🛠️ Local Verification Suite (scripts/verify_hooks.sh): Test runner script that pipes sample JSON payloads to stdin to test your hook scripts locally before deploying.

---

🧭 Captain's Navigation Chart (10-Agent Specs)

AI Coding Agent	Config File Location	Specification Guide
Cursor AI	.cursor/hooks.json	Cursor Hooks Spec
Windsurf (Cascade)	.windsurf/hooks.json	Windsurf Hooks Spec
Claude Code	.claude/settings.json	Claude Code Hooks Spec
Antigravity (AGY)	hooks/prevent.py	Antigravity Spec
Aider AI	.aider.conf.yml	Aider Hooks Spec
Continue CLI (cn)	~/.continue/settings.json	Continue CLI Spec
Roo Code / Cline	.clinerules	Roo Code Spec
OpenHands / Devin	config.toml	OpenHands Spec
GitHub Copilot	.github/copilot-instructions.md	Copilot Spec
Amazon Q	.amazonq/rules	Amazon Q Spec

---

🗺️ Ship Manifest & Repository Layout