# Crush Hooks

Use when the user wants to add, write, debug, or configure a Crush hook, gating or...

- Repository: https://github.com/charmbracelet/crush (28908 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add charmbracelet/crush --skill crush-hooks -g -a claude-code -y`
Codex: `npx skills add charmbracelet/crush --skill crush-hooks -g -a codex -y`
Cursor: `npx skills add charmbracelet/crush --skill crush-hooks -g -a cursor -y`
Gemini CLI: `npx skills add charmbracelet/crush --skill crush-hooks -g -a gemini-cli -y`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.

## Configuration

The rest: https://github.com/charmbracelet/crush/blob/HEAD/internal/skills/builtin/crush-hooks/SKILL.md