Custom Hooks

ClaudeKit hooks automate your workflow by reacting to Claude Code lifecycle events — session start, tool calls, agent completion, and more.

What are Custom Hooks?

Hooks are shell commands configured in ~/.claude/settings.json that fire automatically in response to Claude Code events. Each hook receives JSON context via stdin and can inject guidance, block actions, or persist state.

16 hooks across 5 categories 12 shared utility modules

Hook Lifecycle Events

Hooks react to these Claude Code events:

SessionStart startup, resume, clear, compact

UserPromptSubmit every user prompt

PreToolUse before tool execution

PostToolUse after tool execution

SubagentStart subagent spawned

SubagentStop subagent finished

Stop session ends

TaskCompleted task marked done

TeammateIdle teammate about to idle

Session Lifecycle

4 hooks

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

session-init.cjs EK + MK

Initialize session with project detection, config loading, and environment setup. Fires on startup, resume, clear, and compact.

Triggers: SessionStart

session-state.cjs EK only

Persist and restore session progress across compactions. Saves active plan, todo items, and branch status.

Triggers: PostToolUse Stop SubagentStop

usage-quota-cache-refresh.cjs EK only

Keep usage quota cache warm for statusline. Smart throttling: 60s for prompts, 300s for tool events.

Triggers: SessionStart UserPromptSubmit PostToolUse

usage-context-awareness.cjs EK + MK

Config gate wrapper for usage-quota-cache-refresh. Enables usage awareness via ck-config flag.

Triggers: (config-gated)

Context Injection

3 hooks

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

dev-rules-reminder.cjs EK + MK

Inject session info, development rules, modularization reminders, and active plan context on every prompt.

Triggers: UserPromptSubmit

subagent-init.cjs EK + MK

Inject minimal context (~200 tokens) to subagents using environment variables from SessionStart.

Triggers: SubagentStart

team-context-inject.cjs EK only

Inject peer info and task summary when spawning Agent Team teammates. Non-blocking, fail-open.

Triggers: SubagentStart

Code Quality

3 hooks

Enforce naming conventions, simplification reminders, and plan formatting.

descriptive-name.cjs EK + MK

Enforce descriptive, kebab-case file naming when creating new files.

Triggers: PreToolUse (Write)

simplify-gate.cjs EK only

Replaces post-edit-simplify-reminder. Auto-triggers code-simplifier when edit thresholds (400 LOC / 8 files) are breached.

Triggers: PostToolUse (Edit/Write/MultiEdit)

plan-format-kanban.cjs EK only

Warn when plan.md uses filenames as link text instead of human-readable names.

Triggers: PostToolUse (Edit/Write/MultiEdit)

Security & Safety

2 hooks

Block access to sensitive files and restricted directories.

privacy-block.cjs EK + MK

Block access to sensitive files (.env, credentials). Requires explicit user approval to proceed.

Triggers: PreToolUse (Bash/Glob/Grep/Read/Edit/Write)

scout-block.cjs EK + MK

Block directory access based on .ckignore patterns. Uses gitignore-spec matching.

Triggers: PreToolUse (Bash/Glob/Grep/Read/Edit/Write)

Workflow & Teams

3 hooks

Coordinate planning, task tracking, and team agent collaboration.

cook-after-plan-reminder.cjs EK only

Remind to invoke /ck:cook after Plan subagent completes. Outputs plan path for new sessions.

Triggers: SubagentStop (Plan)

task-completed-handler.cjs EK only

Log task completions and inject progress context when agents mark tasks done.

Triggers: TaskCompleted

teammate-idle-handler.cjs EK only

Inject available task context when a teammate goes idle. Can prevent idle via exit code.

Triggers: TeammateIdle

Deprecated

1 hook

Hooks that are disabled or removed from the active distribution.

skill-dedup.cjs Deprecated EK only

Prevented local skills from shadowing global versions. Disabled in v2.9.1 due to race condition with parallel sessions.

Triggers: (disabled)

Shared Utility Library

All hooks share utility modules under hooks/lib/ for common concerns.

ck-config-utils Read/validate .ck.json configuration

colors ANSI color formatting

config-counter Track skills, hooks, agents counts

context-builder Build session context with WARN 70% / CRITICAL 90% thresholds

git-info-cache Cache git status for performance

hook-logger Structured diagnostics with performance tracking

privacy-checker Block access to sensitive files (.env, credentials)

project-detector Detect project type and package manager

scout-checker Check if scout agents are available

session-state-manager Manage session state persistence

transcript-parser Parse Claude conversation transcripts

usage-limits-cache Atomic cache for usage quota snapshots

More hooks coming soon...

Slack notifications, auto-commit, and more!

Learn more about ClaudeKit built-in hooks at ClaudeKit Documentation