mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
125 lines
4.4 KiB
Markdown
125 lines
4.4 KiB
Markdown
# Claude Code Hooks - Official Guide
|
|
|
|
> Complete official documentation from https://code.claude.com/docs/en/hooks-guide
|
|
|
|
## Automate workflows with hooks
|
|
|
|
Run shell commands automatically when Claude Code edits files, finishes tasks, or needs input. Format code, send notifications, validate commands, and enforce project rules.
|
|
|
|
### Hook lifecycle
|
|
|
|
Hooks fire at specific points during a Claude Code session. The official hook events are:
|
|
|
|
| Event | When it fires |
|
|
| :------------------- | :--------------------------------------------------- |
|
|
| `SessionStart` | When a session begins or resumes |
|
|
| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |
|
|
| `PreToolUse` | Before a tool call executes. Can block it |
|
|
| `PermissionRequest` | When a permission dialog appears |
|
|
| `PostToolUse` | After a tool call succeeds |
|
|
| `PostToolUseFailure` | After a tool call fails |
|
|
| `Notification` | When Claude Code sends a notification |
|
|
| `SubagentStart` | When a subagent is spawned |
|
|
| `SubagentStop` | When a subagent finishes |
|
|
| `Stop` | When Claude finishes responding |
|
|
| `PreCompact` | Before context compaction |
|
|
| `SessionEnd` | When a session terminates |
|
|
|
|
### Hook handler types
|
|
|
|
There are three types of hook handlers:
|
|
|
|
1. **Command hooks** (`type: "command"`): Run a shell command
|
|
2. **Prompt hooks** (`type: "prompt"`): Use Claude model for single-turn evaluation
|
|
3. **Agent hooks** (`type: "agent"`): Spawn subagent with tool access
|
|
|
|
### Configuration structure
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"EventName": [
|
|
{
|
|
"matcher": "ToolName|AnotherTool",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "bash /path/to/script.sh",
|
|
"timeout": 600,
|
|
"async": false
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Hook input (stdin)
|
|
|
|
Common fields for all events:
|
|
- `session_id`: Current session ID
|
|
- `transcript_path`: Path to conversation JSON
|
|
- `cwd`: Current working directory
|
|
- `permission_mode`: Current permission mode
|
|
- `hook_event_name`: Name of the event that fired
|
|
|
|
Event-specific fields depend on the event type.
|
|
|
|
### Hook output (exit codes and stdout)
|
|
|
|
- **Exit 0**: Success. Parse stdout for JSON decision
|
|
- **Exit 2**: Blocking error. stderr text becomes Claude's feedback
|
|
- **Any other code**: Non-blocking error
|
|
|
|
### Tool matchers
|
|
|
|
Available for: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`
|
|
|
|
Tool names:
|
|
- Built-in: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Task`, `WebFetch`, `WebSearch`
|
|
- MCP tools: `mcp__<server>__<tool>` (e.g., `mcp__github__search_repositories`)
|
|
|
|
### Event matchers
|
|
|
|
Different events match on different fields:
|
|
- `SessionStart`: `startup`, `resume`, `clear`, `compact`
|
|
- `SessionEnd`: `clear`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other`
|
|
- `Notification`: `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`
|
|
- `SubagentStart`/`SubagentStop`: agent type (e.g., `Bash`, `Explore`, `Plan`)
|
|
- `PreCompact`: `manual`, `auto`
|
|
|
|
### Hook configuration locations
|
|
|
|
| Location | Scope |
|
|
|----------|-------|
|
|
| `~/.claude/settings.json` | All your projects |
|
|
| `.claude/settings.json` | Single project |
|
|
| `.claude/settings.local.json` | Single project (gitignored) |
|
|
| Plugin `hooks/hooks.json` | When plugin enabled |
|
|
| Skill/Agent frontmatter | While component active |
|
|
|
|
### Best practices
|
|
|
|
✅ **DO:**
|
|
- Use command hooks for deterministic actions
|
|
- Use prompt hooks for judgment-based decisions
|
|
- Use agent hooks when verification requires file inspection
|
|
- Quote all shell variables: `"$VAR"`
|
|
- Use absolute paths with `$CLAUDE_PROJECT_DIR`
|
|
- Set appropriate timeouts
|
|
- Use async hooks for long-running operations
|
|
- Keep hooks fast (< 10 seconds by default)
|
|
|
|
❌ **DON'T:**
|
|
- Trust input data blindly
|
|
- Use relative paths
|
|
- Put sensitive data in hook output
|
|
- Create infinite loops in Stop hooks
|
|
- Run blocking operations without async
|
|
|
|
---
|
|
|
|
See https://code.claude.com/docs/en/hooks-guide for complete guide
|
|
See https://code.claude.com/docs/en/hooks for reference documentation
|