Crush Hooks
Use when the user wants to add, write, debug, or configure a Crush hook, gating or...
Install
npx skills add charmbracelet/crush --skill crush-hooks -g -a claude-code -y- Repository
- charmbracelet/crush28.9k
- Category
- Testing
- Updated
- 3d ago
- License
- See repository
- Context cost
- Mediumabout 2,307 tokens
- Runs scripts
- No, instructions only
What it does
Use when the user wants to add, write, debug, or configure a Crush hook, gating or blocking tool calls, approving or rewriting tool input before execution, injecting context into tool results, or troubleshooting hook behavior in crush.json.
Crush Hooks
Hooks are user-defined commands in crush.json that fire at specific points
during execution, giving deterministic control over tool behavior. They run
before permission checks and only on the top-level agent's tool calls, sub-agent calls (task tool, agentic_fetch, etc.) are not intercepted, though
the sub-agent tool call itself is.
For the full reference, see docs/hooks/README.md. This skill covers what you
need to author correct hooks.
Supported Events
Crush supports 13 hook events: PreToolUse, PostToolUse,
PostToolUseFailure, PermissionRequest, PermissionResult,
SessionStart, SessionEnd, TurnStart, TurnEnd, StopFailure,
Interrupt, PreCompact, PostCompact. Event names are case-insensitive
and accept snake_case (PreToolUse, pretooluse, pre_tool_use all work);
an unknown name is a config error. The five events that carry a tool call
(PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest,
PermissionResult) accept matcher; the rest run every configured hook and
reject matcher.
Only PreToolUse (allow/deny/halt/rewrite/context), PostToolUse
(halt/replace output/context/feedback), PostToolUseFailure
(halt/context), and PreCompact (block) honor output. The rest are
observe-only. Turn and tool events fire only for the top-level agent, never
for sub-agents (agentic_fetch, the task tool), so a TurnEnd hook runs
once per user prompt.
Per-event payload extras: PostToolUse has tool_response (the output
string), PostToolUseFailure and StopFailure have error, TurnEnd has
last_assistant_message, PermissionResult has decision
(granted/denied/cancelled), SessionStart has source
(startup/resume), SessionEnd has reason, and the compaction events
have trigger (auto/manual). Payloads also carry hook_event_name and
tool_use_id, and hooks see CLAUDE_PROJECT_DIR, so scripts written for
Claude Code usually work unchanged.
