Deterministic automation scripts that run at specific lifecycle events
~/.claude/hooks/ |
Config: ~/.claude/settings.json
Hooks are shell scripts or Python programs that run automatically at specific points in Claude Code's lifecycle. Unlike skills (which are prompts) or agents (which are LLM-driven), hooks provide deterministic behavior - they always run and always produce the same output given the same input. Use hooks for security enforcement, audit logging, naming validation, and automated checklists.
Hooks fire in sequence: Session start -> User prompt -> Before each tool -> After each tool -> Session end
Shows a "don't forget" checklist when creating a new project directory under ~/projects/.
Detects mkdir commands targeting new top-level project directories and injects a reminder
about network configuration, GitLab CI/CD setup, standard files, and integrations.
Bashmkdir /home/administrator/projects/NEWEnforces naming conventions for resources created through Claude Code. Validates project directories, container names, and database names against infrastructure standards. Blocks operations that violate naming rules with helpful suggestions.
mkdir ~/projects/My-Project (uppercase)mkdir ~/projects/my-project (hyphen in our project)docker run --name MyContainer (uppercase)CREATE DATABASE MyDB (uppercase)Blocks dangerous operations before they execute. Prevents force pushes to main/master, deletion of secrets directories, recursive deletion of home directory, and production operations without security agent approval.
git push --force origin mainrm -rf secrets/rm -rf /home/administratorLogs all tool calls for compliance and debugging. Creates daily audit logs with timestamps, agent type, tool name, and session ID. For Bash commands, also logs the command text (truncated to 200 chars for security). Auto-rotates logs older than 30 days.
~/.claude/audit/YYYY-MM-DD.log2026-01-18 15:30:45 | Agent: pm | Tool: Bash | Session: abc123 Command: docker compose up -d
Logs session start and detects project context. Checks for CLAUDE.md, project-level agents, and skills in the current directory. Provides informational output about available context.
CLAUDE.md in CWD.claude/agents/.claude/skills/CLAUDE_CWD - Current working directoryCLAUDE_SESSION_ID - Session identifierSummarizes work done when agent stops. Logs session end to audit log. For PM agent sessions, creates a summary file with session details. Auto-cleans summary files older than 7 days.
~/.claude/audit/sessions.log~/.claude/sessions/{session}-summary.txtLogs all user prompts with timestamps. Simple audit hook that records when prompts are submitted to Claude Code. Always allows prompts to proceed (exit 0).
~/.claude/prompt-log.txt| Aspect | Hooks | Skills | Agents |
|---|---|---|---|
| Location | ~/.claude/hooks/ |
~/.claude/skills/ |
~/.claude/agents/ |
| Format | Shell scripts / Python | Markdown prompts | Markdown with config |
| Execution | Deterministic (always runs) | On-demand (LLM chooses) | Task-based (LLM-driven) |
| Can Block | Yes (exit code 1 or 2) | No | No |
| Use Cases | Security, audit, validation | Domain knowledge, procedures | Complex multi-step tasks |
| Example | Block force push to main | How to deploy a service | Deploy entire infrastructure |
Hooks are registered in ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/new-project-checklist.py",
"timeout": 10
}
]
}
]
}
}