hooks
Hook Development Rules
When & Why to Use This Skill
This Claude skill provides a standardized framework and architectural pattern for developing custom hooks within the Claude agent environment. It establishes a robust Shell-to-TypeScript workflow, allowing developers to intercept and manage critical agent events such as tool execution, prompt submission, and session lifecycle. By implementing these development rules, users can extend Claude's functionality with custom logic, enforce operational guardrails, and automate complex environment setups.
Use Cases
- Implementing Guardrails: Use the PreToolUse hook to intercept tool calls, validate parameters, and block unauthorized or unsafe commands before execution.
- Automated Environment Setup: Leverage the SessionStart hook to automatically configure environment variables, pull latest git changes, or initialize databases when a project session begins.
- Custom Audit Logging: Utilize PostToolUse hooks to capture the output of agent actions and send them to external monitoring tools or databases for compliance and debugging.
- Context Enrichment: Use the UserPromptSubmit hook to automatically append project-specific documentation or style guides to every user request, ensuring the agent remains aligned with project standards.
- State Management: Employ PreCompact hooks to save essential session state or summarize progress before the agent's context window is compressed.
| name | hooks |
|---|---|
| description | Hook Development Rules |
| user-invocable | false |
Hook Development Rules
When working with files in .claude/hooks/:
Pattern
Shell wrapper (.sh) → TypeScript (.ts) via npx tsx
Shell Wrapper Template
#!/bin/bash
set -e
cd "$CLAUDE_PROJECT_DIR/.claude/hooks"
cat | npx tsx <handler>.ts
TypeScript Handler Pattern
interface HookInput {
// Event-specific fields
}
async function main() {
const input: HookInput = JSON.parse(await readStdin());
// Process input
const output = {
result: 'continue', // or 'block'
message: 'Optional system reminder'
};
console.log(JSON.stringify(output));
}
Hook Events
- PreToolUse - Before tool execution (can block)
- PostToolUse - After tool execution
- UserPromptSubmit - Before processing user prompt
- PreCompact - Before context compaction
- SessionStart - On session start/resume/compact
- Stop - When agent finishes
Testing
Test hooks manually:
echo '{"type": "resume"}' | .claude/hooks/session-start-continuity.sh
Registration
Add hooks to .claude/settings.json:
{
"hooks": {
"EventName": [{
"matcher": ["pattern"], // Optional
"hooks": [{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/hook.sh"
}]
}]
}
}