MemoryLake
Back to all articles
TutorialNovember 13, 2026·12 min read

What Are Claude Code Hooks? Which Ones Can Add Context for Claude, Why a Resumed Session Replays Old Hook Output, and When CLAUDE.md Is the Better Place (2026)

You wrote a small hook that tells Claude Code the current branch and the latest CI result every time you submit a prompt. It works well. Then you resume yesterday's session with --continue, ask about the build, and Claude confidently reports yesterday's CI status and a commit that's since been replaced. The hook didn't fail. Claude Code replayed what it said yesterday.

Anthropic's hooks reference describes exactly this: "For mid-session events like PostToolUse or UserPromptSubmit, when you resume with --continue or --resume, Claude Code replays the saved text rather than re-running the hook for past turns, so values like timestamps or commit SHAs become stale."

Hooks are a flexible way to give Claude Code context, and an easy one to misread. This guide covers what hooks are, where they're defined, which hook events can add context for Claude, where that context lands, what happens to it on resume and after compaction, how hooks shape the compaction summary, and when a CLAUDE.md file is the better place for the same information.

What Claude Code hooks are

Anthropic's definition: "Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute automatically at specific points in Claude Code's lifecycle."

They run in more places than the terminal. "Claude Code fires the same hook events wherever it runs: sessions in the terminal, IDE extensions, the Desktop app, and cloud sessions."

Each hook is attached to an event. The reference lists dozens, from SessionStart when a session begins or resumes, to PreToolUse before a tool call runs, to PreCompact and PostCompact around compaction, to SessionEnd when a session terminates.

Hooks can also do side-effect work, such as formatting files after an edit, blocking a risky command, or sending a notification. This guide is about the subset that puts text into Claude's context, because that text behaves like memory, with some rules of its own.

Where hooks are defined

Where you define a hook sets its scope. The reference lists the locations:

  • ~/.claude/settings.json for all your projects, local to your machine.
  • .claude/settings.json for a single project, and can be committed to the repo.
  • .claude/settings.local.json for a single project, not shared.
  • Managed policy settings for an organization, controlled by admins.
  • A plugin's hooks/hooks.json while the plugin is enabled.
  • Skill or subagent frontmatter while that skill or subagent is in use.

Hook entries combine rather than replace each other. "Hook entries merge across settings levels rather than replacing each other: user, project, and local settings add their own hooks without removing managed ones".

One limit is worth knowing for remote work: "Cloud sessions don't read your local ~/.claude/settings.json." A hook you rely on locally won't run in a cloud session unless it's defined somewhere the cloud session reads.

To see what's configured, type /hooks. Anthropic describes it as "a read-only browser for your configured hooks" that labels each hook with where it comes from.

Which hooks can add context for Claude

Not every hook can talk to Claude. The ones that can use a field called additionalContext. Anthropic explains: "The additionalContext field passes a string from your hook into Claude's context window."

Where that text appears depends on the event:

  • SessionStart and SubagentStart: "at the start of the conversation, before the first prompt"
  • UserPromptSubmit and UserPromptExpansion: "alongside the submitted prompt"
  • PreToolUse, PostToolUse, PostToolUseFailure, and PostToolBatch: "next to the tool result"
  • Stop and SubagentStop: at the end of the turn, so Claude can act on the feedback
  • PostModelSwitch: "with the next request after the switch"

For UserPromptSubmit, plain output works too. The reference describes two channels, plain stdout and additionalContext, and says: "Neither channel produces a visible transcript entry."

That's the part that surprises people. Claude Code wraps the text in a system reminder: "Claude reads the reminder on the next model request, but it doesn't appear as a chat message in the interface." Claude sees it, and the chat doesn't show it.

If you want to see what hooks added, the transcript view shows more of the session than the chat does. We covered it in our guide to what transcript view shows in Claude Code.

How much context a hook can add

There's a size limit. "If a value exceeds 10,000 characters, Claude Code writes the text to a file in the session directory and passes Claude the file path with a preview of up to the first 2,000 characters instead. Claude can read the file, but Claude Code doesn't ask it to."

So a hook that dumps a long report doesn't put the whole report in front of Claude. It puts a preview and a path, and whether Claude opens the file is up to Claude.

When several hooks fire on the same event, all of them count. "When several hooks return additionalContext for the same event, Claude receives all of the values."

How to write context a hook adds

Anthropic gives specific advice on wording: "Write the text as factual statements rather than imperative system instructions."

The reason is security. Text that sounds like a command from outside the conversation can look like a prompt injection. Anthropic warns that such framing "can trigger Claude's prompt-injection defenses, which causes Claude to surface the text to you instead of treating it as context".

The examples it gives read as plain facts: "The deployment target is production" or "This repo uses bun test". It also lists the kinds of information hooks are good for:

  • Environment state: the current branch, deployment target, or feature flags
  • Conditional project rules: which test command applies to the file just edited, which directories are read-only in a worktree
  • External data: open issues, recent CI results, content from an internal service

What these have in common is that they change. That's the reason to use a hook instead of a file.

Why a resumed session replays old hook output

Here's the behavior from the introduction, in full. "Claude Code saves the injected text in the session transcript."

When you come back to a session, the past turns aren't re-run. "For mid-session events like PostToolUse or UserPromptSubmit, when you resume with --continue or --resume, Claude Code replays the saved text rather than re-running the hook for past turns, so values like timestamps or commit SHAs become stale."

In practice, Claude sees what your hooks said at the time. If a hook reported a CI status, a branch, or an issue list yesterday, that's what's in the resumed conversation's history, next to the turns where it fired.

SessionStart is the exception. Anthropic says SessionStart hooks run again on resume, with the source field set to resume, or to fork if you added --fork-session, "so they can refresh their context".

So if you want fresh values in a resumed session, a SessionStart hook with a resume matcher is the documented place for them. The older values are still in the history, so it helps for the new text to say what's current.

What happens to hook context at compaction

Compaction summarizes earlier parts of a conversation to free space. Anthropic's hooks guide is direct about the risk: "This can lose important details."

Hook text sits in the conversation history, which is what compaction summarizes. Hooks give you two ways to manage that.

Re-inject after compaction. SessionStart has a compact matcher, which fires after auto or manual compaction. The guide's recommendation: "Use a SessionStart hook with a compact matcher to re-inject critical context after every compaction."

Shape the summary itself. PreCompact runs before compaction, and its output has a special role. "When a PreCompact hook exits 0 and doesn't block, Claude Code uses its stdout as instructions for the compaction summary." The same 10,000-character cap applies, and longer output is cut at the cap.

PreCompact can also block compaction, with different results depending on timing. If compaction was triggered proactively, blocking it means the conversation continues uncompacted. If it was triggered to recover from a context-limit error, "the underlying error surfaces and the current request fails".

PostCompact receives the summary that was generated, in a field called compact_summary, which is useful for logging or updating notes outside Claude Code. The reference lists it with no decision control, for side effects like logging.

The SessionStart matchers

Because SessionStart is the main way hooks refresh context, its matchers are worth knowing. The reference lists five:

  • startup for a new session
  • resume for --resume, --continue, or /resume
  • clear for /clear
  • compact for auto or manual compaction
  • fork for a new session forked from an existing one

There's a timing detail too. At launch and after /clear, SessionStart hooks run in the background so you can type right away, but "Claude's first response still waits for the hooks to finish, so their context reaches Claude." The reference also says that if you run /clear or switch conversations while background hooks are still running, nothing they return applies to the session.

When CLAUDE.md is the better place

Anthropic answers this directly in the reference: "For instructions that never change, prefer CLAUDE.md. It loads without running a script and is the standard place for static project conventions."

The SessionStart section says the same: "For static context that doesn't require a script, use CLAUDE.md instead."

A simple test: if the text would be the same every time the hook runs, it belongs in CLAUDE.md. If it depends on the moment, such as the branch, the time, or the latest build, a hook is the right tool.

CLAUDE.md has its own behavior around compaction. The reference notes an InstructionsLoaded load reason of compact, which fires when instruction files are re-loaded after a compaction. If you've been putting static rules in a hook to make them survive compaction, CLAUDE.md is the documented home for them. To check how your CLAUDE.md files load and what they cost, see our guide to what /doctor checks in Claude Code.

Turning hooks off

To remove a hook, delete its entry from the settings file. To turn all hooks off temporarily, the reference describes a disableAllHooks setting, which follows settings precedence. Admins have a stronger version: with allowManagedHooksOnly in managed settings, user, project, local, and plugin hooks are blocked.

If a hook's context seems to have vanished, check those two settings before debugging the script.

What people try first

Trusting values in a resumed session. Mid-session hook output is replayed from the transcript, so timestamps and commit SHAs can be stale.

Looking for hook output in the chat. Added context doesn't appear as a chat message.

Putting static rules in a hook. Anthropic recommends CLAUDE.md for instructions that never change.

Writing hook text as commands. Imperative framing can trigger prompt-injection defenses.

Returning a long report. Over 10,000 characters, Claude gets a preview and a file path.

Expecting local hooks in cloud sessions. Cloud sessions don't read your local user settings.

The Fix: Give Claude current context without stale leftovers

Step 1: Move static rules to CLAUDE.md

If a hook always says the same thing, put that text in CLAUDE.md instead.

Step 2: Refresh on resume and after compaction

Use SessionStart with resume and compact matchers for values that change.

Step 3: Write facts, keep them short

Phrase hook output as factual statements, label what's current, and stay under 10,000 characters.

Step 4: Write down the reasons

Keep the decisions behind your conventions, such as why a directory is read-only or why a test command differs, somewhere that isn't regenerated each session.

Setting this up in MemoryLake

Hooks are good at the present tense: what branch you're on, what CI says right now. CLAUDE.md is good at fixed conventions. Neither is built for the decisions that change slowly and need to reach more than one tool, such as why the team chose a migration order or which approach was already ruled out.

MemoryLake is a memory layer for that kind of project context, such as decisions, constraints, and conventions, kept in one place you maintain and available to the assistants you connect, such as ChatGPT, Claude Code, and Codex.

You write the entries yourself, in your own words. Nothing is read out of, written to, or deleted from your hooks, your settings files, your CLAUDE.md files, your session transcripts, your compaction summaries, or any vendor's store. Hooks, compaction, and resume work the way Anthropic describes them.

Step 1: Create an API key

Sign in and generate a key from the dashboard. Store it outside your repositories and out of hook scripts, like any other credential.

The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent
The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent

Step 2: Upload your first memories

Start with what you wrote in Step 4 of the fix: the reasons behind your conventions and the decisions your hooks assume. One decision per entry.

The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory
The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory

Step 3: Connect your AI & agents

Connect Claude Code and any other assistants you use. Hooks keep supplying the current state, and the reasoning is available alongside it.

The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer
The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer

What this changes in practice

The first difference is a cleaner split. Hooks carry what changes by the minute, CLAUDE.md carries fixed conventions, and the slower-moving decisions have their own place.

The second is less stale context. Decisions aren't frozen into a transcript at the moment a hook fired.

The third is continuity across tools. Codex or another assistant working on the same repository can use the same decisions without its own hook setup.

Best practices for Claude Code hooks

Use hooks for what changes. Branches, builds, and issue lists, not fixed rules.

Put fixed rules in CLAUDE.md. It loads without running a script.

Refresh on resume. Only SessionStart re-runs when you resume.

Plan for compaction. Use a compact matcher to re-inject what matters, or PreCompact to guide the summary.

Write facts, not commands. It keeps hook text from looking like an injection.

Stay under the size cap. Long output becomes a file path and a preview.

Check /hooks when something's missing. It shows where each hook comes from.

Conclusion

Claude Code hooks run automatically at points in a session's lifecycle, and several of them can add context for Claude through additionalContext: SessionStart, SubagentStart, UserPromptSubmit, the tool events, Stop, and PostModelSwitch, among others. That text reaches Claude as a system reminder and doesn't appear as a chat message.

Claude Code saves hook text in the transcript and replays it on resume for past turns, so values can go stale, and only SessionStart runs again. Use SessionStart matchers and PreCompact to manage context across resume and compaction, keep static rules in CLAUDE.md, and keep the decisions behind your setup somewhere that isn't regenerated each session.

Frequently asked questions

What are hooks in Claude Code?

User-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that run automatically at specific points in Claude Code's lifecycle.

Can a hook add context for Claude?

Yes. Several events, including SessionStart, UserPromptSubmit, and the tool events, can return additionalContext, which Claude reads as a system reminder.

Why does Claude see old hook output after I resume?

Claude Code saves injected text in the transcript and replays it for past turns instead of re-running the hook, so values like timestamps and commit SHAs can be stale.

Do hooks run again when I resume a session?

SessionStart hooks run again on resume. Mid-session hooks for past turns are replayed, not re-run.

How do I keep context after compaction?

Use a SessionStart hook with a compact matcher to re-inject it, or a PreCompact hook to give instructions for the compaction summary.

Should I use a hook or CLAUDE.md?

Anthropic recommends CLAUDE.md for instructions that never change. Use hooks for context that changes, like the current branch or CI results.

Why doesn't my hook run in cloud sessions?

Cloud sessions don't read your local ~/.claude/settings.json.