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

> Discover Claude Code SessionStart hook matcher patterns in the i-have-adhd repo. Learn how anchored regex identifies session initialization markers.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-22

---

**The Claude Code SessionStart hook matcher patterns are anchored regular expressions defined in [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.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:

```javascript
// 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
});

```

```python

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) provides the integration metadata linking these hooks to the Claude plugin system.