Claude Code v2.1.71

User Hooks

Lifecycle event hooks configured in ~/.claude/settings.json
that persist context and enforce quality across sessions

Active Script: ~/.claude/hooks/context-save-check.sh

linuxserver.lan — ai-servicers.com  |  Official Hooks Docs

What Is a Hook?

A hook is a script that Claude Code runs automatically at a specific point in its lifecycle. Claude Code supports several hook types; this deck focuses on command hooks — shell scripts that receive a JSON payload on stdin and return text on stdout.

Command hooks are deterministic — unlike skills (LLM prompts) or agents (autonomous), they always execute the same logic. They can remind, block, or inject context without any AI interpretation.

Official docs: docs.anthropic.com/en/docs/claude-code/hooks

Input (stdin)

  • session_id — current session
  • cwd — working directory
  • hook_event_name — which event fired
  • Event-specific fields (tool name, trigger, etc.)

Output (stdout)

  • Empty — silent, no effect
  • Text — injected as reminder to agent
  • Exit 2 — blocks the operation
  • JSON — advanced control (permissions)

Command Hooks vs Skills vs Agents

Command Hooks

Skills

Agents

What
Shell scripts (bash, python)
Markdown knowledge files (SKILL.md)
Autonomous LLM instances with scoped tools
Execution
Deterministic — same input, same output
Non-deterministic — LLM interprets & applies
Non-deterministic — goal-driven, multi-turn
Trigger
Automatic at lifecycle events
On-demand via /name or auto-detected
Delegated by parent agent or user
Can Block?
Yes — exit 2 stops the operation
No — advisory only
No — does work, doesn't gate it
AI Involved
None — pure code execution
Interprets — text becomes prompt
Full AI — own context window
Config
settings.json
~/.claude/skills/
~/.claude/agents/
Use For
Guardrails, reminders, validation, audit
Domain knowledge, workflows, best practices
Parallel tasks, specialized roles, delegation

Key insight: Only command hooks can stop an action before it executes. Skills advise, agents act, hooks enforce.

Hook Event Categories

Claude Code exposes 19 lifecycle events across 4 categories

Lifecycle

Stopagent finishes turn
SessionStartsession begins
SessionEndsession terminates
PreCompactbefore compaction
Setupinitial setup

Tool

PreToolUsebefore execution
PostToolUseafter success
PostToolUseFailureafter failure
PermissionRequestasks permission

Agent

SubagentStartspawned
SubagentStopfinished
TeammateIdleidle
TaskCompletedtask done

System

UserPromptSubmitprompt sent
Notificationnotification
InstructionsLoadedcontext loaded
ConfigChangeconfig updated
WorktreeCreateworktree added
WorktreeRemoveworktree removed

View full payload reference →   |   Official docs: docs.anthropic.com/en/docs/claude-code/hooks

Configured Hooks

These 4 hooks fire at every point where knowledge could be lost

Stop
+
SubagentStop
+
PreCompact
+
SessionEnd

Stop — Primary Save Point

Agent finished its work. The natural moment to reflect on what changed and update docs/context/.

SubagentStop — Delegated Work

Subagents (Explore, custom agents) often make significant changes. Their work must be captured before the parent continues.

PreCompact — Before Memory Wipe

Compaction erases conversation history to reclaim context window. Last chance to save context before it's gone.

SessionEnd — Final Save

Session is terminating (exit, clear, logout). Absolute last opportunity to persist anything. No second chances.

Three-Tier Response Logic

The hook script uses git diff to determine reminder intensity

Silent

No output. Context docs already updated, or stop_hook_active is true. Also silent outside git repos.

Trigger: docs/context/ changed in diff

Soft Reminder

Gentle nudge. No code changes or <15 lines of diff.

"If your changes affect architecture, security, or operations, update docs/context/."

Strong Reminder

Explicit file list. 15+ lines of diff but docs/context/ untouched.

"You made significant changes but did not update docs/context/."

git diff
→
count lines
→
check docs/context/
→
select tier

Projects without docs/context/ get: "Run /context-save init to scaffold project context files"

Adding a Hook

You don't need to edit config files manually. Just tell Claude what you want.

Step 1: Write Your Script

Create a shell script in ~/.claude/hooks/. It reads JSON from stdin and prints text to stdout.

Step 2: Ask Claude to Wire It Up

"Add a Stop hook that runs ~/.claude/hooks/my-script.sh"
Claude updates ~/.claude/settings.json for you — or use /hooks to manage interactively.

Step 3: It Just Works

Hooks activate immediately. No restart needed. Claude runs your script at every matching event and injects the output as a system message.

Scope: User hooks (~/.claude/settings.json) apply across all projects  |  Project hooks (.claude/settings.json) apply per-repo

Official docs: docs.anthropic.com/en/docs/claude-code/hooks

Context-Driven Development

The context-save Skill + Hook

AI agents are stateless by default. Every new session starts from zero. The context-save skill and its 4 hooks solve this by ensuring that project knowledge is captured into files before it can be lost — whether the agent stops, a subagent finishes, the context compacts, or the session ends.

Without context-save

  • Each session rediscovers the same gotchas
  • Architectural decisions are forgotten
  • Compaction silently erases hard-won knowledge
  • New agents repeat mistakes of previous agents
  • Context lives only in conversation (ephemeral)

With context-save

  • Knowledge persists in docs/context/
  • Hooks ensure nothing slips through the cracks
  • New sessions inherit all previous learnings
  • Context survives compaction and session boundaries
  • Context lives in git (versioned, diffable, permanent)

Context-Driven Development: treat project context as a first-class artifact — committed, reviewed, and evolved alongside the code.

What Gets Saved

Files in docs/context/ — a reconstruction blueprint

requirements.md Business rules, user workflows, product constraints
architecture.md Components, boundaries, data flow, service topology
interfaces.md API contracts, schemas, entities, events, config surfaces
conventions.md Code patterns, naming, frameworks, libraries, module layout
security.md Auth, secrets, trust boundaries, access rules
operations.md Deployment, containers, networking, config, runtime
testing.md Critical paths, regression checks, coverage strategy
gotchas.md Sharp edges, workarounds, forbidden changes, failure traps

/context-save init scaffolds all files from templates

Full Reference Page  |  ai-servicers.com