Modular Python application that handles Claude Code hook events and dispatches them to Slack notifications, voice feedback (Zundamon TTS), and JSONL event logging with session tracking.
A modular Python application that handles Claude Code hook events and dispatches them to various notification systems including Slack, voice feedback, and structured logging.
This skill provides a comprehensive hook handler system for Claude Code that:
1. Claude Code sends JSON events via stdin to `all_hooks.py`
2. Event dispatcher (`src/core/dispatcher.py`) routes events to enabled handlers
3. Three handlers process events in parallel:
- **Slack Notifier**: Thread-based notifications with session tracking
- **Zunda Speaker**: Voice feedback via TTS
- **Event Logger**: JSONL logging with rotation
Install development tools and dependencies:
```bash
aqua install
uv sync
```
Set up required environment variables in your shell profile or `.env` file:
**Slack Configuration (required for Slack notifications):**
```bash
export CCHH_SLACK_BOT_TOKEN="xoxb-your-token-here"
export CCHH_SLACK_CHANNEL_ID="C01234567890"
export CCHH_SLACK_NOTIFICATIONS_ENABLED="true" # default: true
export CCHH_SLACK_SHOW_SESSION_START="true" # default: true
export CCHH_SLACK_NOTIFY_ON_TOOL_USE="true" # default: true
export CCHH_SLACK_NOTIFY_ON_STOP="true" # default: true
export CCHH_SLACK_COMMAND_MAX_LENGTH="200" # default: 200
```
**Optional Configuration:**
```bash
export CCHH_ZUNDA_SPEAKER_ENABLED="true" # Voice feedback (default: true)
export CCHH_EVENT_LOGGING_ENABLED="true" # Event logging (default: true)
export CCHH_LOG_MAX_SIZE_MB="100" # Log rotation size (default: 100)
export CCHH_LOG_ROTATION_COUNT="5" # Log rotation count (default: 5)
export CCHH_TEST_ENVIRONMENT="0" # Set to "1" to disable notifications
```
Edit `~/.claude/settings.json` and add hook configurations. **Replace `/path/to/cchh` with the actual repository path:**
```json
{
"permissions": {
"defaultMode": "acceptEdits"
},
"hooks": {
"PreToolUse": [
{
"hooks": [
{
"type": "command",
"command": "cd /path/to/cchh && uv run python all_hooks.py"
}
]
}
],
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "cd /path/to/cchh && uv run python all_hooks.py"
}
]
},
{
"hooks": [
{
"type": "command",
"command": "cd /path/to/cchh && uv run python ruff_hook.py"
}
]
}
],
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "cd /path/to/cchh && uv run python all_hooks.py"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "cd /path/to/cchh && uv run python all_hooks.py"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "cd /path/to/cchh && uv run python all_hooks.py"
}
]
}
],
"PreCompact": [
{
"hooks": [
{
"type": "command",
"command": "cd /path/to/cchh && uv run python all_hooks.py"
}
]
}
]
}
}
```
**Important Notes:**
**Essential Commands:**
```bash
uv run task test
uv run task lint
uv run task format
uv run task typecheck
uv run task all
uv run task clean
```
**Specific Test Commands:**
```bash
uv run pytest tests/slack/test_notifier.py -v
uv run pytest --cov=src --cov-report=term-missing
uv run pytest tests/core/test_dispatcher.py::TestEventDispatcher -v
```
**Log File Locations:**
**Common Troubleshooting:**
1. **Import errors**: Ensure PYTHONPATH includes project root
2. **Slack not working**: Verify `CCHH_SLACK_BOT_TOKEN` and `CCHH_SLACK_CHANNEL_ID` are set correctly
3. **Tests failing**: Run `aqua install` then `uv sync` to update dependencies
4. **Debug mode**: Set `CCHH_TEST_ENVIRONMENT=1` to disable external notifications during development
To add a new handler:
1. Create a new module in `src/` directory
2. Implement the `HookHandler` interface from `src/core/base.py`:
```python
from src.core.base import HookHandler
class MyHandler(HookHandler):
def handle(self, event_name: str, event_data: dict) -> None:
# Your implementation
pass
```
3. Register the handler in `all_hooks.py` dispatcher
4. Add configuration options to `src/utils/config.py`
5. Write unit tests in `tests/`
6. Update documentation
**Tech Stack:**
**Code Quality:**
**Event Type Support:**
Once configured, the hooks run automatically on Claude Code events:
1. **PreToolUse**: User sees command about to execute → Handler logs, sends Slack notification, speaks command
2. **PostToolUse**: Command completes → Handler logs result, threads Slack message, runs Ruff formatter (if Python file)
3. **Notification**: Claude sends notification → Handler logs, Slack notifies, voice feedback
4. **Stop**: Session ends → Handler logs, Slack summarizes session, clears state
5. **UserPromptSubmit**: User submits prompt → Handler logs, tracks conversation flow
6. **PreCompact**: Context overflow warning → Handler alerts via all channels
All events are logged to `~/.cchh/logs/events.jsonl` for later analysis.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/cchh-claude-code-hook-handler/raw