Claude Code SessionStart Hook Matcher Patterns in the i-have-adhd Repository

The Claude Code SessionStart hook matcher patterns are anchored regular expressions defined in hooks/hooks.json that identify session initialization markers such as [Claude] Session Started at the start of output lines.

The ayghri/i-have-adhd repository provides a hook system for detecting when Claude Code sessions begin, enabling automated context initialization and logging. Understanding these Claude Code SessionStart hook matcher patterns is essential for modifying session detection behavior or troubleshooting hook execution failures according to the repository source code.

Where the Matcher Patterns Are Defined

The repository stores hook configurations in the central manifest file hooks/hooks.json. Within this JSON structure, the Claude entry contains a matchers array that holds the regular expression strings used to identify session start events. These patterns are stored as escaped JSON strings to properly handle regex special characters.

The specific patterns include:

• ^\\[Claude\\] Session Started — Matches lines beginning with the literal text [Claude] Session Started
• ^\\[Claude\\] New Conversation — Matches lines beginning with the literal text [Claude] New Conversation

Both patterns utilize the caret anchor (^) to ensure they only trigger when the markers appear at the beginning of a line, preventing false positives from similar text appearing in the middle of output.

How Pattern Matching Works

When Claude Code generates output, the runtime evaluates each line against the regex patterns in the matchers array. If any line satisfies one of the defined regular expressions, the system registers the event as a session start and dispatches the associated hook logic. This mechanism triggers downstream initialization procedures such as context setup, state reset, or notification events.

The matching logic executes in the always-on hook implementation found in hooks/always-on.mjs, which continuously monitors output streams and compares them against the configured patterns before invoking the appropriate callback handlers.

Key Implementation Files

Several files work together to implement the SessionStart hook detection system:

• hooks/hooks.json — Contains the declarative configuration including the matchers array with regex strings for Claude session detection.
• hooks/always-on.mjs — Implements the runtime logic that evaluates output lines against the matcher patterns and executes hook callbacks when matches occur.
• .claude-plugin/plugin.json — The Claude-specific plugin manifest that references the hook definitions and integrates them into the broader plugin architecture.

Practical Code Examples

You can interact with these patterns programmatically to test matchers or build custom integrations:

// Example: Registering a hook that responds to SessionStart events
import { registerHook } from '@claude/plugin';

// The hook utilizes the matcher patterns defined in hooks.json
registerHook('sessionStart', async (event) => {
  console.log('Claude session initialized – loading user context...');
  // Custom initialization logic here
});

# Example: Testing lines against the raw matcher patterns

import json
import re

with open('hooks/hooks.json') as f:
    hooks = json.load(f)

# Compile the escaped regex patterns from the matchers array

claude_matchers = hooks['claude']['matchers']
patterns = [re.compile(p) for p in claude_matchers]

def is_session_start(line):
    """Check if a line matches any Claude SessionStart pattern."""
    return any(p.search(line) for p in patterns)

# Test the patterns

print(is_session_start("[Claude] Session Started"))  # → True

print(is_session_start("Some random text"))            # → False

Summary

• Claude Code SessionStart hook matcher patterns are regex strings stored in hooks/hooks.json under the matchers array.
• The patterns ^\\[Claude\\] Session Started and ^\\[Claude\\] New Conversation use start-of-line anchors to detect session initialization.
• The hooks/always-on.mjs file implements the matching logic that monitors output and triggers hooks when patterns match.
• These patterns enable automated initialization workflows whenever Claude begins a new session or conversation.

Frequently Asked Questions

What format are the SessionStart matcher patterns stored in?

The patterns are stored as JSON-escaped regular expression strings in the matchers array within hooks/hooks.json. The double backslashes (e.g., ^\\[Claude\\]) are necessary to escape regex special characters within the JSON format, compiling to single backslashes in the actual regex engine.

How does the runtime know when to trigger the SessionStart hook?

The runtime continuously evaluates output lines against the compiled regex patterns defined in the configuration. When a line matches any pattern in the matchers array—specifically beginning with [Claude] Session Started or [Claude] New Conversation—the system flags the event as a session start and executes the registered hook callbacks in hooks/always-on.mjs.

Can I add custom patterns to detect different session markers?

Yes, you can extend the matchers array in hooks/hooks.json with additional regex strings. Ensure each pattern uses the ^ anchor to match the start of lines only, and properly escape backslashes for JSON compatibility (e.g., ^\\[Custom\\] Init). After modifying the file, restart the Claude Code runtime to load the updated patterns.

Where is the hook logic actually executed when a pattern matches?

The execution logic resides in hooks/always-on.mjs, which contains the implementation that checks matcher results against incoming output streams. This file dispatches the session start events to registered handlers after confirming a pattern match, while .claude-plugin/plugin.json provides the integration metadata linking these hooks to the Claude plugin system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}