keepcalculator

06 Numbers and Powers

Claude Code Hook JSON: What Stays Consistent, What Varies

Card No. 06·71842 · Updated · Standard formula, shown below

When you configure hooks in Claude Code, the JSON structure itself stays consistent across all hook events, but the content of the matcher and hooks fields changes depending on which event you are targeting. The top-level schema is always the same: a JSON object with a matcher string and a hooks array. However, the specific values you put inside those fields—like the event name in the matcher and the command, timeout, and context in each hook object—vary by event and use case.

What the Hook JSON Looks Like

Here is the general shape of a Claude Code hook configuration, as defined in your project's .claude/settings.json file:

{
  "hooks": {
    "matcher": "EventName",
    "hooks": [
      {
        "matcher": "specific-sub-event",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 30,
            "context": {}
          }
        ]
      }
    ]
  }
}

This structure is the same for every event type. The outer hooks object always has a matcher (the event name) and a hooks array. Each item in that array is another object with its own matcher and hooks array. The innermost hook objects contain the actual command to run, an optional timeout, and an optional context object.

What Stays Consistent

The following elements are identical across all hook configurations:

  • File location: Hooks are always defined in .claude/settings.json (project-level) or ~/.claude/settings.json (user-level).
  • Top-level keys: The outer object always has hooks as the key, containing an object with matcher and hooks.
  • Hook object keys: Every individual hook object has the same three optional keys: type (currently always "command"), command (a string), timeout (a number in seconds), and context (an object).
  • Matcher format: The matcher is always a string that identifies the event (or sub-event) you're hooking into.
  • JSON syntax: The file must be valid JSON—no comments, no trailing commas, and double quotes for strings.

What Varies

The variable parts are the values you choose for each field:

  • Event name in the matcher: The top-level matcher changes to one of the supported events: PreToolUse, PostToolUse, Notification, UserPromptSubmit, Stop, SubagentStop, PreCompact, SessionStart, SessionEnd.
  • Sub-event matchers: For PreToolUse and PostToolUse, the inner matcher specifies which tool (e.g., Read, Write, Edit, Bash) triggers the hook. For other events, it may be a specific condition like always or a notification type.
  • Command: This is the shell command that runs when the hook is triggered. It varies entirely based on what you want to accomplish—running a linter, sending a notification, or logging data.
  • Timeout: The number of seconds before the hook is killed. The default is 60 seconds, but you can set it lower or higher depending on how long your command needs.
  • Context: An object that provides additional information to the command, such as tool input, workspace, or hook-specific data. The contents vary by event and by what you need to pass.

How to Choose the Right Matcher

Choosing the correct matcher is the most important decision. Here's a quick guide:

  • PreToolUse: Runs before a tool is executed. Use this to validate inputs, block certain tools, or modify the tool's input. The inner matcher should be the tool name (e.g., Bash, Write).
  • PostToolUse: Runs after a tool completes. Use this to check outputs, run tests, or log results. Inner matcher is the tool name.
  • Notification: Runs when Claude sends a notification (e.g., needs permission, needs user input). Inner matcher can be always or a specific notification type.
  • UserPromptSubmit: Runs when the user submits a prompt. Inner matcher is typically always.
  • Stop: Runs when Claude finishes responding. Inner matcher is always.
  • SubagentStop: Runs when a subagent finishes. Inner matcher is always.
  • PreCompact: Runs before context compaction. Inner matcher is always.
  • SessionStart: Runs at the start of a session. Inner matcher is always.
  • SessionEnd: Runs at the end of a session. Inner matcher is always.

Common Mistakes and Misconceptions

One common mistake is assuming the inner matcher is optional. For PreToolUse and PostToolUse, you must specify which tool you're hooking. Using always won't work—it will simply never match. Another mistake is forgetting that the outer matcher must exactly match the event name, including case. pretooluse will not trigger anything.

A frequent misconception is that the context field is where you define variables for your command. In reality, context is an input that Claude Code passes to your command via environment variables (like CLAUDE_HOOK_CONTEXT). You don't define the context; you read it. The context key in the hook object is for specifying which context data to include (e.g., {"tool_input": true}), not for arbitrary key-value pairs.

Practical Example: A PreToolUse Hook

Suppose you want to run a Python script before every Bash command to check for dangerous commands. Your hook JSON would look like this:

{
  "hooks": {
    "matcher": "PreToolUse",
    "hooks": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/check.py",
            "timeout": 30,
            "context": {
              "tool_input": true
            }
          }
        ]
      }
    ]
  }
}

Here, the outer matcher is PreToolUse, the inner matcher is Bash, and the command runs your script. The context tells Claude Code to include the tool's input in the environment variable, so your script can inspect the command.

How to Test and Debug Your Hooks

To test a hook, simply run a Claude Code session and trigger the event. If the hook fails, you'll see an error message in the CLI. You can also check the logs in ~/.claude/logs/ for more details. A useful debugging technique is to start with a simple command like echo "hook ran" to confirm the hook is firing, then gradually build up to your real command. Also, ensure your command is in the system PATH or use an absolute path—Claude Code doesn't always run hooks in a login shell, so your usual PATH may not be loaded.

Frequently Asked Questions

Can I use multiple hooks for the same event?

Yes, you can have multiple hook objects in the hooks array for the same matcher. They will run sequentially in the order they appear. For example, you could have two PreToolUse hooks for Bash: one to validate input and another to log the command.

What happens if my hook times out?

If a hook exceeds its timeout, Claude Code kills it and continues. The hook's output is ignored, and you'll see a warning in the session. You can increase the timeout if your command legitimately needs more time, but be careful not to set it so high that it blocks the session for too long.

Can I pass arguments to my command in the hook?

Yes, you can include arguments in the command string, just like you would in a shell. For example, "command": "python3 script.py --verbose" works. However, you cannot use shell features like pipes or redirection directly—the command is executed as a single process. To use pipes, wrap it in bash -c "...".

Does the order of hooks matter?

Yes, hooks are executed in the order they appear in the array. If you have multiple hooks for the same event, the first one runs first. This can be important if one hook modifies the tool input that another hook depends on.

Can I use environment variables in the command?

Yes, the command is executed in a shell, so environment variables are expanded. You can also read the hook context from the CLAUDE_HOOK_CONTEXT environment variable, which is a JSON string containing the context you requested.

What if I make a syntax error in the JSON?

Claude Code will fail to parse the settings file and may ignore all hooks or show an error. Always validate your JSON with a linter before saving. A missing comma or an extra quote can silently disable all hooks.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →