Feature: Hooks and Automation
Relevant source files
The following files were used as context for generating this wiki page:Hooks and automation in Claude Code provide a powerful mechanism to enforce development conventions, automate repetitive tasks, and integrate quality gates directly into the development lifecycle. By executing custom scripts at specific points in the workflow, this feature allows for actions like auto-formatting code, running tests, blocking direct edits to protected branches, and intelligently suggesting context-specific "skills" to the AI.
This system is primarily configured through .claude/settings.json and can be extended with shell or Node.js scripts located in the .claude/hooks/ directory. The automation capabilities also extend into CI/CD pipelines via GitHub Actions Workflows.
Sources: README.md:9-16, .claude/settings.json
Hook Configuration
The central configuration for all hooks is located in .claude/settings.json. This file defines which scripts to run in response to specific hook events. A human-readable documentation of the configured hooks can be found in .claude/settings.md.
Sources: README.md:120-122, .claude/settings.md
Hook Events
The system supports several event types that trigger hook execution at different points in the Claude Code lifecycle.
| Event | When It Fires | Common Use Cases |
|---|---|---|
PreToolUse | Before a tool is executed | Block edits on the main branch, validate commands |
PostToolUse | After a tool successfully completes | Auto-format code, run tests, lint files |
UserPromptSubmit | When a user submits a prompt | Add context, suggest relevant skills |
Stop | When the agent finishes its task | Decide if the agent should continue working |
Sources: README.md:126-133
Hook Response and Exit Codes
Hooks can communicate back to the Claude Code environment using a specific JSON format and standard exit codes to control the workflow.
Hook Response Format:
A hook script can output a JSON object to stderr to provide feedback or block an action.
{
"block": true,
"message": "Reason for blocking",
"feedback": "Informational message",
"suppressOutput": true,
"continue": false
}
Sources: README.md:135-144
Exit Codes:
The exit code of a hook script determines its outcome.
| Exit Code | Meaning |
|---|---|
0 | Success |
2 | Blocking error (for PreToolUse only) |
| Other | Non-blocking error |
Sources: README.md:146-150
Hook Implementations
Pre-Tool-Use Hook: Branch Protection
A primary use case for PreToolUse hooks is to enforce repository rules, such as preventing direct edits to the main branch. The hook executes a shell command that checks the current Git branch. If it's main, the hook exits with code 2 and returns a JSON message, blocking the tool execution.
The following diagram illustrates the flow for this branch protection hook.
Sources: README.md:100-111, .claude/settings.json:4-15
This is configured in .claude/settings.json as follows:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
"timeout": 5
}
]
}
]
}
}
Sources: .claude/settings.json:3-16
User-Prompt-Submit Hook: Skill Evaluation
A more advanced automation is the skill evaluation system, which is triggered by the UserPromptSubmit event. This system analyzes the user's prompt to intelligently suggest which "skills" Claude should activate for the given task. This ensures that project-specific conventions for testing, UI patterns, or debugging are consistently applied.
Sources: README.md:21-23, CLAUDE.md:46-55
The process involves several steps, managed by a shell script (skill-eval.sh) that orchestrates the analysis.
The diagram below shows the workflow of the skill evaluation hook.
Sources: README.md:231-253
This system is configured using three key files:
.claude/hooks/skill-eval.sh: The main script triggered by the hook..claude/hooks/skill-eval.js: A Node.js engine for more complex pattern matching and logic (as referenced inREADME.md)..claude/hooks/skill-rules.json: A JSON file defining the rules, keywords, and patterns for matching prompts to skills.
Sources: README.md:229, .claude/hooks/skill-eval.sh, .claude/hooks/skill-rules.json
An example rule from skill-rules.json for testing patterns:
{
"testing-patterns": {
"description": "Jest testing patterns and TDD workflow",
"priority": 9,
"triggers": {
"keywords": ["test", "jest", "spec", "tdd", "mock"],
"keywordPatterns": ["\\btest(?:s|ing)?\\b", "\\bspec\\b"],
"pathPatterns": ["**/*.test.ts", "**/*.test.tsx"],
"intentPatterns": [
"(?:write|add|create|fix).*(?:test|spec)",
"(?:test|spec).*(?:for|of|the)"
]
},
"excludePatterns": ["e2e", "maestro", "end-to-end"]
}
}
Sources: .claude/hooks/skill-rules.json, README.md:255-272
To enable this hook, the following configuration is added to .claude/settings.json:
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/skill-eval.sh",
"timeout": 5
}
]
}
]
}
}
Sources: README.md:278-291
GitHub Actions Workflows
The automation strategy extends beyond the local environment into the CI/CD pipeline using GitHub Actions. These workflows leverage Claude Code to perform automated tasks like code reviews on pull requests and scheduled maintenance.
Sources: README.md:330-333
PR Code Review
A GitHub Action can be configured to run the code-reviewer agent on every pull request. It can also be triggered by commenting @claude on a PR, allowing for on-demand reviews. The action uses git diff to identify changes and applies a predefined review checklist.
Sources: README.md:335-337, README.md:340-360
Scheduled Maintenance
The repository also defines several scheduled workflows that run automatically to maintain code quality, documentation, and dependencies.
| Workflow | Schedule | Purpose |
|---|---|---|
| Code Quality | Weekly (Sunday) | Reviews random directories and auto-fixes issues. |
| Docs Sync | Monthly (1st) | Ensures documentation is aligned with recent code changes. |
| Dependency Audit | Biweekly (1st & 15th) | Performs safe dependency updates and verifies with tests. |
Sources: README.md:362-368
Summary
The Hooks and Automation feature is a cornerstone of the Claude Code integration in this repository. It provides a flexible and powerful way to enforce standards, reduce manual effort, and improve code quality proactively. By combining local hooks (PreToolUse, PostToolUse, UserPromptSubmit) with CI/CD automation via GitHub Actions, the system creates a comprehensive quality and productivity net that operates throughout the entire development lifecycle.
Sources: README.md:13-23, README.md:380-387