Claude Code Hooks Ecosystem
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Code Hooks Ecosystem is a collection of event handlers designed to manage session state, automate cross-session memory, and facilitate state preservation within the Continuous Claude system. These hooks allow the environment to respond to specific triggers—such as starting a session or completing a tool use—to ensure that context remains high-fidelity across clear operations. Sources: CLAUDE_ONBOARDING.md:14-17, CLAUDE_ONBOARDING.md:58-58
The ecosystem operates by intercepting lifecycle events and executing scripts that manage external "ledgers" and local memory databases. This architectural pattern solves the problem of lossy context compaction in Claude Code by enabling a "clear-and-reload" workflow instead of degrading context through multiple summaries. Sources: CLAUDE_ONBOARDING.md:20-23, CLAUDE.md:129-131
Architecture and Integration
The hook system follows a specific pattern where a shell wrapper invokes a TypeScript handler. This separation ensures portability across different shell environments while maintaining complex logic within a typed language. Sources: CLAUDE_ONBOARDING.md:124-124, CLAUDE_ONBOARDING.md:139-139
Component Relationship
The ecosystem integrates tightly with the session management lifecycle and the claude-mem plugin.
The diagram above illustrates the flow from a Claude Code trigger through the hook execution layers to the persistent storage of session state. Sources: CLAUDE_ONBOARDING.md:124-124, CLAUDE.md:131-140
Key Hooks and Triggers
| Hook Event | Purpose | Integration Point |
|---|---|---|
SessionStart | Injects prior context and auto-loads ledgers. | context-hook.js |
PostToolUse | Automatically captures observations from tool executions. | save-hook.js |
UserPromptSubmit | Captures user prompts for future recall. | user-message-hook.js |
Stop | Generates session summaries via Claude Agent SDK. | summary-hook.js |
Sources: CLAUDE_ONBOARDING.md:58-58, CLAUDE.md:131-140
Hook Execution Logic
Hooks are registered in .claude/settings.json. When triggered, they communicate via JSON objects. A hook can either allow a process to continue or block it based on internal validation logic. Sources: CLAUDE_ONBOARDING.md:58-58, CLAUDE_ONBOARDING.md:140-140
Data Flow for Memory Hooks
The claude-mem plugin utilizes five distinct layers to ensure cross-session memory persistence:
- Hooks Layer: HTTP clients that notify the worker.
- Worker Service: A Bun-managed API (port 37777) that handles state.
- MCP Server: A search interface for the LLM to access memory.
- Service Layer: Manages session state, vector sync (ChromaSync), and search logic.
- Data Layer: Persistent SQLite and Chroma databases.
Sources: CLAUDE.md:131-148
This sequence diagram shows how a tool execution event is captured and stored locally without requiring external API keys. Sources: CLAUDE.md:131-148, CLAUDE.md:179-183
Installation and Setup
Hooks are installed globally into ~/.claude/hooks/ during the setup process. This directory is then symlinked or referenced by project-level configurations. Sources: install-global.sh:417-422, init-project.sh:176-178
Deployment Configuration
The global installation script handles the lifecycle of hook files, ensuring they are pre-bundled to avoid requiring npm install within each individual project. Sources: install-global.sh:424-426
| Path | Purpose |
|---|---|
~/.claude/hooks/ | Pre-bundled JS/TS hook logic. |
.claude/settings.json | Registration of event handlers to hook scripts. |
~/.claude/.env | Environment variables (e.g., CLAUDE_PROJECT_DIR) required by hooks. |
Sources: install-global.sh:424-430, tests/test_artifact_index.py:80-82
Manual Testing
Developers can manually test hook integration by piping mock JSON events into the shell wrappers:
echo '{"type":"resume"}' | .claude/hooks/session-start-continuity.sh
Sources: CLAUDE_ONBOARDING.md:149-149
Conclusion
The Claude Code Hooks Ecosystem serves as the primary automation layer for the Continuous Claude workflow. By leveraging lifecycle events like SessionStart and PostToolUse, the system successfully offloads context management to local markdown ledgers and databases. This architecture ensures that even after a context clear, the LLM can resume work with full fidelity by reloading structured state from the hook-managed storage. Sources: CLAUDE_ONBOARDING.md:20-23, CLAUDE.md:141-143