Claude Code Ignoring Your CLAUDE.md? Hooks Fix That

Over on Threads (come say hi!), I sometimes see posts from others lamenting the fact that Claude Code is not following the instructions in their CLAUDE.md file. Based on what I can gather from the posts, it sounds like they want a guaranteed action. Claude Code isn't always compliant, and if you've already tried working with Claude Code's CLAUDE.md and auto memory and it's still failing, this Claude Code tutorial on hooks may be for you.

 

I've experienced the same frustration in some of my projects. CLAUDE.md is used to help Claude Code understand the project with context and is a venue to give it guidance. This guidance is analyzed, interpreted, and acted upon by Claude Code in its own way of "thinking".

 

Claude Code uses two types of instructions in most of its configuration files. One is the prompt, which is what is contained in the CLAUDE.md file, and the other is FrontMatter, which is the YAML portion in many of Claude Code's configuration files. Unfortunately, CLAUDE.md doesn't allow for FrontMatter, so any instructions given to Claude Code in the CLAUDE.md file are prompts, not hard instructions. If you want Claude Code to take a guaranteed action every time something specific happens, not just when it feels like it, you'll need a hook.

 

What is a Claude Code Hook?

 

A hook is a deterministic tool that reliably runs regardless of what Claude Code is doing. Hooks are based on an event model, so as events occur within Claude Code, listeners, called matchers, are used to determine when the hook should fire. Matchers are regex strings.

 

Some common matchers are:

 

• Bash: Claude Code is about to run a terminal command.
• Write: Claude Code is creating a new file.
• Edit: Claude Code is modifying an existing file.
• Write|Edit: Claude Code is creating a new file or editing an existing file. The pipe symbolizes "or".
• Read: Claude Code is reading a file.
• Grep: Claude Code is searching for text inside of files.
• "": Claude Code does anything. No filter.

 

You can find a complete list of matchers in the official Anthropic documentation on Matcher Patterns.

 

What are some Claude Code Hook Events?

 

Hook events are the trigger moments when hooks fire. Hooks can be set up to fire on many different kinds of events, such as these. For a full list, visit the official Anthropic documentation on Hooks.

 

• SessionStart - when a Claude Code session starts or resumes
• UserPromptSubmit - when the user submits a prompt to Claude Code but before it's processed
• Notification - when Claude Code sends a notification
• Stop - when Claude Code stops responding
• TaskCompleted - when Claude Code marks a task as completed
• PreToolUse - before a tool is called
• PostToolUse - after a tool completes successfully

 

What are some Claude Code Hook Handlers?

 

Hook handlers are the actions you want taken by Claude Code when a hook fires. There are four types of hook handlers.

 

• Command Hooks: runs a shell command. Accepts JSON input and returns exit codes and data to stdout.
• HTTP Hooks: sends JSON input to an HTTP POST and returns the endpoint's output in JSON format.
• Prompt Hooks: sends a prompt to a Claude Code model. Returns a yes/no response in JSON format.
• Agent Hooks: will spawn a subagent and return a decision.

 

For example, if you want a BASH script to execute, you would set up a Command Hook. If you wanted to make an API call and return its results, you could use an HTTP Hook.

 

For more detailed information on Hook Handlers, visit the official Anthropic Documentation on Hook Handler Fields.

 

How are Claude Code Hooks Configured?

 

Hooks are configured in ~/.claude/settings.json, .claude/settings.json, or .claude/settings.local.json, depending on the scope. Claude Code has a slash command to create hooks from within the user interface called /hooks.

 

 

 

 

Let's Configure a Real Claude Code Hook

 

The title of this article is Claude Code Hooks: The Fix for When Claude Code Ignores Your Instructions, so let's use a hook to make it remember your instructions.

 

From Claude Code, let's add a file to the project called context.md that contains the context you want to always preserve. Tell Claude Code the name of the deployment server and the root application folder.

 

❯ add .claude/context.md                                                                                                                  

 

● Read 1 file (ctrl+o to expand)                                                                                                          

 

● What content would you like in .claude/context.md? Or should I create it as an empty file / with a default template?                    

 

❯ The deployment server is claudecodetutorials.com and the root application folder is appserver.

 

Press Enter, and you'll see that Claude Code has written the file:

 

● Write(.claude/context.md)                                                                                                               
  ⎿  Wrote 6 lines to .claude/context.md                                                                                                  
     # Project Context                                                                                                                    

 

     ## Deployment                                                                                                                        

 

     - **Server:** claudecodetutorials.com                                                                                               
     - **Root application folder:** appserver

 

● Created .claude/context.md with the deployment server and root folder info.

 

Now let's create a hook that will be called every time a session starts so that your context persists across sessions. Before we do that, let's review where you can create hooks:

 

Location	Scope	Shareable
~/.claude/settings.json	All your projects	No, local to your machine
.claude/settings.json	Single project	Yes, can be committed to the repo
.claude/settings.local.json	Single project	No, gitignored

 

You can find more information about Claude Code Hook Locations in the official Anthropic documentation on Hook Locations.

 

From the same Claude Code prompt, add (or edit, if already created) the .claude/settings.json file:

 

❯ Add .claude/settings.json                                                                                                               

 

● Write(.claude/settings.json)                                                                                                            
  ⎿  Wrote 1 lines to .claude/settings.json                                                                                               
     {}                                                                                                                                   

 

● Created .claude/settings.json as an empty JSON object. What settings would you like to add?

 

Now paste this code at the Claude Code prompt:

 

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cat .claude/context.md"
          }
        ]
      }
    ]
  }
}

 

Before moving forward, let's discuss what this JSON actually does.

 

• The first "hooks" line defines this JSON as being a Claude Code Hook configuration.
• The "SessionStart" is the event for which the hook should fire. In this case, we want this hook to run every time the session starts.
• The "matcher" in this case is irrelevant because no matchers are available for SessionStart, but if this were a different type of event, you could have "Bash" if running a terminal command, or "Edit" if performing a file edit. SessionStart only does one thing, and that's to start the session, which is why there is no matcher value here.
• The second "hooks" line is an array of hooks handlers. In this instance, we're using the Command hook handler.
• The "command" line is the actual terminal command used by the Command hook handler. We're simply reading the .claude/context.md file and writing it to stdout.

 

After pasting the JSON, Claude Code will modify the .claude/settings.json file, adding the new hook configuration and confirms that it will run at the beginning of every session and inject the context automatically.

 

● Write(.claude/settings.json)
  ⎿  Added 15 lines, removed 1 line
       1 -{}                                                                                                                              
       1   No newline at end of file                                                                                               
       2 +{                                                                                                                               
       3 +  "hooks": {                                                                                                             
       4 +    "SessionStart": [                                                                                                    
       5 +      {                                                                                                                  
       6 +        "matcher": "",                                                                                                   
       7 +        "hooks": [                                                                                                       
       8 +          {                                                                                                              
       9 +            "type": "command",                                                                                           
      10 +            "command": "cat .claude/context.md"                                                                          
      11 +          }                                                                                                              
      12 +        ]                                                                                                                
      13 +      }                                                                                                                  
      14 +    ]                                                                                                                    
      15 +  }                                                                                                                      
      16 +}                                                                                                                        
      17   No newline at end of file

 

● Done. This hook will run cat .claude/context.md at the start of every session, injecting the deployment context automatically.

 

Now let's try it.

 

Exit the current Claude Code instance with exit:

 

❯ /exit                                                                                                                                   
  ⎿  Bye!

 

Now restart Claude with claude -c or claude --continue.

 

Ask Claude Code to provide you with the deployment server and deployment path:

 

❯ What is the deployment server and deployment path?                                                                                      

 

● From the session context:                                                                                                               

 

  - Deployment server: claudecodetutorials.com                                                                                           
  - Root application folder: appserver

 

As you can see, Claude Code recalled the deployment server and deployment path correctly.

 

With as many people who seem to have trouble getting Claude Code to remember context, you now have another tool in your arsenal to force it to remember the most important items in your project. Remember that hooks always fire regardless of what Claude Code is wanting to do, so that gives you the advantage when wanting it to perform something it may not think to consistently perform on its own.

 

Preparing for the CCA exam? Start with our overview: What Is Anthropic's Claude Certified Architect Exam?