How hooks work

ClaudeKit Hooks

Think of hooks as guard rails around Claude Code.

A hook is a small script that listens for a lifecycle moment, reads the current context, then helps Claude Code continue in a safer or more useful way.

16 hooks 5 categories

Diagram of ClaudeKit hooks as guard rails: user intent flows into Claude Code lifecycle events, hooks inspect JSON context, then allow, block, inject context, or remember session state.

Read the flow before reading hook names

Every ClaudeKit hook follows the same simple pattern. Once this pattern is clear, each hook below becomes easier to understand.

A moment happens

Claude Code starts a session, receives a prompt, prepares to use a tool, edits a file, or finishes a task.

Claude sends context

The hook receives JSON context: event name, tool target, working directory, active task, and related session state.

The hook checks a rule

ClaudeKit compares that context against project rules, project settings, ignored paths, privacy patterns, or workflow state.

Claude continues with guidance

The hook can let work continue, block risky work, inject context, or remember state for the next step.

They are not prompt templates

A prompt tells the model what to do. A hook can inspect context and enforce a rule before work continues.

Four results to remember

Allow

Let safe work continue.

Block

Stop risky access or unsafe actions.

Inject

Add rules, team context, or reminders.

Remember

Persist useful session state.

Hook list

ClaudeKit hooks by role

Scan each group from top to bottom. Every hook shows three quick signals: default state, whether it can stop an action, and the smallest way to turn it off.

Default state

ON means active in the current guardrail set. OFF means source exists but the hook is opt-in or not registered by default.

Disable safely

Open a hook to copy the smallest .claude/.ck.json flag needed to silence it.

If a hook errors

Unexpected crashes fail open. Claude continues, but you may lose that guard, reminder, context, or state update.

Will a broken hook stop my flow?

Usually no. ClaudeKit hooks are written to fail open on unexpected crashes, so normal work can continue. The exception is intentional policy blocking: privacy, scout, simplify, or artifact gates may return a block when the rule really matches.

Session Lifecycle

Initialize, persist, and monitor session state throughout the lifecycle.

4 hooks

session-init.cjs Sets up the workspace context when Claude Code starts, so later hooks know the project, config, and environment. Engineer Kit + Marketing Kit Default OFF Source still ships, but new installs do not register generated context hooks by default. Adds context Injects useful context for the main agent or subagents. Details

Triggers: SessionStart (startup/resume/clear/compact)
Simple example: You open Claude Code inside a repo. This hook detects the project, config, package manager, and branch so later hooks know the workspace.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "session-init": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but Claude may lose that extra context or cached awareness.
How this hook works: Initialize session with project detection, config loading, and environment setup. Fires on startup, resume, clear, and compact.

session-state.cjs Keeps track of active plans, todos, and branch state so a session can recover after compaction or handoff. Engineer Kit Default OFF Source still ships, but new installs do not register generated context hooks by default. Saves state Records progress so later steps can recover or summarize it. Details

Triggers: PostToolUse (Task/TaskCreate/TaskUpdate/TodoWrite) Stop SubagentStop
Simple example: After compaction or handoff, ClaudeKit can restore the active plan and todo list instead of treating the session as blank.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "session-state": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but progress/state may not be recorded for the next step.
How this hook works: Persist and restore session progress across compactions. Saves active plan, todo items, and branch status.

usage-quota-cache-refresh.cjs Refreshes quota information in the background so statusline data is available without slowing every prompt. Engineer Kit Default OFF Source still ships, but new installs do not register generated context hooks by default. Adds context Injects useful context for the main agent or subagents. Details

Triggers: SessionStart (startup/resume/clear/compact) UserPromptSubmit PostToolUse (Task/TaskCreate/TaskUpdate/TodoWrite)
Simple example: A statusline can show quota context from cache without making every prompt wait for a fresh quota check.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "usage-quota-cache-refresh": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but Claude may lose that extra context or cached awareness.
How this hook works: Keep usage quota cache warm for statusline. Smart throttling: 60s for prompts, 300s for tool events.

usage-context-awareness.cjs Acts as the on/off switch for quota awareness when a project wants that context. Engineer Kit + Marketing Kit Default OFF Source still ships, but new installs do not register generated context hooks by default. Adds context Injects useful context for the main agent or subagents. Details

Triggers: (optional setting)
Simple example: If a project enables usage awareness, this hook lets quota context appear. If not enabled, it stays quiet.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "usage-context-awareness": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but Claude may lose that extra context or cached awareness.
How this hook works: Optional switch for usage-quota-cache-refresh. It only adds quota awareness when enabled in .claude/.ck.json.

Context Injection

Inject rules, environment info, and team context into prompts and subagents.

3 hooks

dev-rules-reminder.cjs Adds the important project rules back into each prompt so the agent does not forget local conventions. Engineer Kit + Marketing Kit Default OFF Source still ships, but new installs do not register generated context hooks by default. Adds context Injects useful context for the main agent or subagents. Details

Triggers: UserPromptSubmit
Simple example: You ask for a UI edit. The hook adds project rules back into context, such as read README first and do not revert unrelated changes.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "dev-rules-reminder": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but Claude may lose that extra context or cached awareness.
How this hook works: Inject session info, development rules, modularization reminders, and active plan context on every prompt.

subagent-init.cjs Gives each new subagent the minimum context it needs instead of dumping the whole session. Engineer Kit + Marketing Kit Default OFF Source still ships, but new installs do not register generated context hooks by default. Adds context Injects useful context for the main agent or subagents. Details

Triggers: SubagentStart
Simple example: A review subagent starts. It receives the task and compact repo context, not the entire main conversation.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "subagent-init": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but Claude may lose that extra context or cached awareness.
How this hook works: Inject minimal context (~200 tokens) to subagents using environment variables from SessionStart.

team-context-inject.cjs Helps agent teammates know who is doing what, reducing duplicated work in team-mode runs. Engineer Kit Default OFF Source still ships, but new installs do not register generated context hooks by default. Adds context Injects useful context for the main agent or subagents. Details

Triggers: SubagentStart
Simple example: In a team run, a frontend teammate can see which file another teammate owns, reducing duplicated edits.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "team-context-inject": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but Claude may lose that extra context or cached awareness.
How this hook works: Inject peer info and task summary when spawning Agent Team teammates. Non-blocking, fail-open.

Code Quality

Enforce naming conventions, simplification reminders, and plan formatting.

3 hooks

descriptive-name.cjs Stops vague new filenames early and nudges the agent toward descriptive kebab-case names. Engineer Kit + Marketing Kit Default ON Registered in the current default guardrail set. Guidance only Adds a reminder or warning, then lets work continue. Details

Triggers: PreToolUse (Write)
Simple example: If the agent tries to create `utils.ts`, the hook nudges it toward a clearer name like `format-campaign-countdown.ts`.
How to turn it off: Set the hook flag to false in .claude/.ck.json. Delete the line, or set it back to true, to re-enable.

json · .claude/.ck.json

{ "hooks": { "descriptive-name": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but the reminder or warning may be missing.
How this hook works: Enforce descriptive, kebab-case file naming when creating new files.

simplify-gate.cjs Warns or blocks shipping when the diff is getting too large and needs simplification first. Engineer Kit Default OFF Available as an opt-in gate; it only acts after you enable its gate config. Can block When enabled, an intentional policy match can stop the current tool/action. Details

Triggers: UserPromptSubmit
Simple example: Before shipping, a very large diff can trigger a warning or block so the agent simplifies the change first.
How to turn it off: The gate is off by default. If you enabled it, turn off the hook flag or set simplify.gate.enabled to false. Emergency bypass: CK_SIMPLIFY_DISABLED=1.

json · .claude/.ck.json

{ "hooks": { "simplify-gate": false }, "simplify": { "gate": { "enabled": false } } }
If this hook errors: Unexpected crashes fail open, so normal work continues. A real policy match can still intentionally block the current action.
How this hook works: Opt-in gate (gate.enabled=false by default). Hard-blocks ship/merge/pr/deploy/publish and soft-warns commit/finalize/release when the working tree carries a large unsimplified diff (400 LOC / 8 files / 200 LOC single-file). Bypass via env CK_SIMPLIFY_DISABLED=1 or .ck.json hooks.simplify-gate=false.

plan-format-kanban.cjs Keeps plan links readable by catching file-name-only link text. Engineer Kit Default OFF Source still ships, but new installs do not register generated context hooks by default. Guidance only Adds a reminder or warning, then lets work continue. Details

Triggers: PostToolUse (Edit/Write/MultiEdit)
Simple example: If a plan link only says `task-1.md`, the hook asks for human-readable link text so the plan is easier to scan.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "plan-format-kanban": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but the reminder or warning may be missing.
How this hook works: Warn when plan.md uses filenames as link text instead of human-readable names.

Security & Safety

Block access to sensitive files and restricted directories.

2 hooks

privacy-block.cjs Blocks sensitive files such as .env or credentials until the user explicitly approves access. Engineer Kit + Marketing Kit Default ON Registered in the current default guardrail set. Can block When enabled, an intentional policy match can stop the current tool/action. Details

Triggers: PreToolUse (Bash/Glob/Grep/Read/Edit/Write)
Simple example: A tool tries to read `.env`. The hook blocks the read and asks for explicit user approval first.
How to turn it off: Set the hook flag to false in .claude/.ck.json. Delete the line, or set it back to true, to re-enable.

json · .claude/.ck.json

{ "hooks": { "privacy-block": false } }
If this hook errors: Unexpected crashes fail open, so normal work continues. A real policy match can still intentionally block the current action.
How this hook works: Block access to sensitive files (.env, credentials). Requires explicit user approval to proceed.

scout-block.cjs Protects ignored or restricted folders using .ckignore patterns before tools read or edit them. Engineer Kit + Marketing Kit Default ON Registered in the current default guardrail set. Can block When enabled, an intentional policy match can stop the current tool/action. Details

Triggers: PreToolUse (Bash/Glob/Grep/Read/Edit/Write)
Simple example: A tool tries to inspect a folder ignored by `.ckignore`. The hook blocks it before the agent reads or edits that path.
How to turn it off: Set the hook flag to false in .claude/.ck.json. Delete the line, or set it back to true, to re-enable.

json · .claude/.ck.json

{ "hooks": { "scout-block": false } }
If this hook errors: Unexpected crashes fail open, so normal work continues. A real policy match can still intentionally block the current action.
How this hook works: Block directory access based on .ckignore patterns. Uses gitignore-spec matching.

Workflow & Teams

Coordinate planning, task tracking, and team agent collaboration.

4 hooks

cook-after-plan-reminder.cjs When planning is done, reminds the agent to move into implementation with the right next command. Engineer Kit Default OFF Source still ships, but new installs do not register generated context hooks by default. Guidance only Adds a reminder or warning, then lets work continue. Details

Triggers: SubagentStop (Plan)
Simple example: When the planning agent finishes, this hook points the next step toward implementation with the generated plan path.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "cook-after-plan-reminder": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but the reminder or warning may be missing.
How this hook works: Remind to invoke /ck:cook after Plan subagent completes. Outputs plan path for new sessions.

task-completed-handler.cjs Records task completions so progress stays visible across agents and later session steps. Engineer Kit Default OFF Used by Agent Teams flows; not part of the normal single-agent default. Saves state Records progress so later steps can recover or summarize it. Details

Triggers: TaskCompleted
Simple example: A teammate marks a task complete. The hook records that progress so the next agent can see what is already done.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "task-completed-handler": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but progress/state may not be recorded for the next step.
How this hook works: Log task completions and inject progress context when agents mark tasks done.

teammate-idle-handler.cjs When a teammate is about to go idle, gives it available work or lets the run continue cleanly. Engineer Kit Default OFF Used by Agent Teams flows; not part of the normal single-agent default. Guidance only Adds a reminder or warning, then lets work continue. Details

Triggers: TeammateIdle
Simple example: A teammate is about to go idle. The hook can hand it remaining work or let it shut down cleanly.
How to turn it off: It is already off in new installs. If a project manually restored the hook command, set this flag to false or remove the settings entry.

json · .claude/.ck.json

{ "hooks": { "teammate-idle-handler": false } }
If this hook errors: Unexpected crashes fail open. The flow continues, but the reminder or warning may be missing.
How this hook works: Inject available task context when a teammate goes idle. Current implementation is non-blocking and fail-open.

workflow-artifact-gate.cjs Checks review artifacts before finalize or ship-like actions, so the workflow does not skip evidence. Engineer Kit Default OFF Available as an opt-in gate; it only acts after you enable its gate config. Can block When enabled, an intentional policy match can stop the current tool/action. Details

Triggers: PreToolUse (finalize stage) manual CLI
Simple example: Before finalize, the hook checks that verification and review artifacts exist so the workflow does not skip evidence.
How to turn it off: It is off by default. If you opted in, set the hook flag or workflow gate to false. Emergency bypass: CK_WORKFLOW_ARTIFACT_GATE_DISABLED=1.

json · .claude/.ck.json

{ "hooks": { "workflow-artifact-gate": false }, "workflowArtifactGate": { "enabled": false } }
If this hook errors: Unexpected crashes fail open, so normal work continues. A real policy match can still intentionally block the current action.
How this hook works: Validate ck:fix/ck:cook review artifacts (context-snippets, verification, review-decision, risk-gate) before finalize and ship-like actions. Optional via .claude/.ck.json; fail-open on crash.

Learn more about ClaudeKit built-in hooks at ClaudeKit Documentation