Claude Hooks

Ruby DSL for Claude Code hooks

v1.4.0 just released and is introducing a great number of changes. Please read the CHANGELOG for more information.

A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will hopefully make creating and configuring new hooks way easier.

Why use this instead of writing bash, or simple ruby scripts?
You might also be interested in my other project, a Claude Code statusline that shows your Claude usage in realtime, inside Claude Code ✨.

📖 Table of Contents

- Ruby DSL for Claude Code hooks
  - 📖 Table of Contents
  - 🚀 Quick Start
  - 📦 Installation
  - 🏗️ Architecture
  - 🪝 Hook Types
  - 🚀 Claude Hook Flow
  - 📚 API Reference
  - 📝 Example: Tool usage monitor
  - 🔄 Hook Output
  - 🔌 Plugin Hooks Support
  - 🛠️ MCP Tools Integration
  - 🚨 Advices
  - ⚠️ Troubleshooting
  - 🧪 CLI Debugging
  - 🐛 Debugging
  - 🧪 Development \& Contributing

🚀 Quick Start

Examples are available in example_dotclaude/hooks/. The GithubGuard in particular is a good example of a solid hook. You can also check Kyle's hooks for some great examples

Claude Code supports two types of hooks:
- Command hooks (type: "command") - Execute Ruby/bash scripts (what this DSL is for)
- Prompt-based hooks (type: "prompt") - Delegate decisions to an LLM (see guide)

Here's how to create a simple command hook with this DSL:

1. Install the gem:

1. Create a simple hook script

3. ⚠️ Make it executable

4. Register it in your .claude/settings.json

That's it! Your hook will now add context to every user prompt. 🎉

Need to run multiple hooks for the same event and merge their outputs? See Multi-hook structure below.

📦 Installation

Install it globally (simpler):

Using a Gemfile

Unless you use bundle exec in the command in your…