The hook system intercepts events from Claude Code in real time. crewkit uses hooks to collect telemetry, track subagent tasks, and enforce conventions.
How hooks work
- crewkit generates a hook settings JSON file when starting a session
- Claude Code is launched with these settings, which register crewkit as a hook handler
- When events occur, Claude Code invokes crewkit's hook handler with the event data
- Events are forwarded to the main crewkit process for processing and API delivery
Events are batched and sent to the crewkit API for storage and analysis.
Event types
crewkit handles 12 event types — 10 standard Claude Code hooks plus 2 custom crewkit hooks.
Standard hooks
| Event | When it fires | What crewkit does |
|---|---|---|
| SessionStart | Session begins | Initialize telemetry |
| SessionEnd | Session ends | Finalize metrics, trigger analysis |
| UserPromptSubmit | User submits a prompt | Track turn count, convention checking |
| PreToolUse | Before a tool runs | Can modify or deny tool execution |
| PostToolUse | After a tool succeeds | Track tool usage patterns |
| PermissionRequest | Permission dialog shown | Track permission patterns |
| Stop | Main agent finishes | Capture completion state |
| SubagentStop | Subagent finishes | Extract subagent stats from JSONL |
| PreCompact | Before context compaction | Track compaction events |
| Notification | System notification | Track notifications |
Custom crewkit hooks
| Event | When it fires | What crewkit does |
|---|---|---|
| SubagentStart | Task tool spawns a subagent | Track subagent creation |
| SubagentStop | Subagent completes | Extract stats: tokens, cost, duration, model |
Subagent stats
When a subagent (Task) completes, crewkit extracts stats from its JSONL transcript:
- Agent type — Which agent was used
- Duration — How long the task ran
- Tokens — Input, output, cache read, cache creation
- Model — Which Claude model was used
- Turns — Assistant and user turns
- Tool usage — Tool uses and results count
This data powers the per-agent analytics in the dashboard.
Event sanitization
Events are sanitized on your machine before being sent to the API, and again by the API before they are stored. How much each event keeps depends on your organization's capture mode: minimal, structured (the default) or full. Capture modes lists what each mode sends, stores and analyses.
Convention handlers
Hooks can detect convention violations in real time. When a tool use violates a playbook convention (e.g., using RSpec when the convention says MiniTest), the hook system logs a challenge.
Convention handler dispatch is being rolled out progressively.