How the SessionStart Hook Works in i-have-adhd: Automatic ADHD Mode Injection

The SessionStart hook in i-have-adhd automatically injects ADHD-focused formatting rules into every Claude session by running a Node.js script that checks for an opt-in flag file and outputs the ruleset from SKILL.md as the first assistant message.

The ayghri/i-have-adhd repository provides a Claude plugin that leverages the SessionStart hook to enforce consistent, ADHD-friendly communication patterns. When activated, this hook ensures that every new session begins with a specific ruleset that guides Claude's responses. Understanding this mechanism requires examining three core components: the hook registration, the execution script, and the ruleset itself.

Hook Registration in hooks.json

The entry point for the SessionStart functionality resides in hooks/hooks.json. This configuration file declares a SessionStart hook that executes the always-on.mjs script whenever a session begins.

The matcher pattern "startup|resume|clear|compact" ensures the hook fires across various session launch scenarios, including fresh starts and context restoration. The configuration specifies a Node command that runs the script located at hooks/always-on.mjs.

The always-on.mjs Script Logic

The hooks/always-on.mjs file contains a lightweight Node.js module that executes three distinct operations to determine whether and how to inject the ADHD ruleset.

Opt-in Detection

The script first checks for the presence of an opt-in flag file. By default, it looks for $CLAUDE_CONFIG_DIR/.i-have-adhd-always, which resolves to ~/.claude/.i-have-adhd-always in standard installations. If this file does not exist, the script exits silently with status code 0, leaving the session completely untouched and preventing any unwanted interference with standard Claude behavior.

Ruleset Loading and Processing

When the flag file exists, the script resolves the absolute path to skills/i-have-adhd/SKILL.md and reads its contents. It then strips the leading YAML front-matter block (delimited by --- markers) to extract only the actionable ruleset content. This processing ensures that metadata headers do not clutter the user's initial session view.

Output Emission

Finally, the script writes a banner message followed by the cleaned ruleset to stdout. Claude captures this output and presents it as the initial assistant message for the session. The implementation includes error handling that guarantees a no-op exit if any step fails, ensuring the hook never blocks or delays session startup regardless of file system issues or configuration errors.

The SKILL.md Ruleset

The actual content injected into sessions originates from skills/i-have-adhd/SKILL.md. This file contains comprehensive ADHD-focused guidelines that direct Claude to lead with the next action, number multi-step tasks, provide specific time estimates, and other accessibility-focused formatting rules.

Because the SessionStart hook outputs this content as the first message, the rules establish immediate context for the entire conversation. The guidelines remain active until the user explicitly types "stop adhd mode" to disable them for the current session.

Enabling and Disabling Always-On Mode

The SessionStart hook respects explicit user consent through filesystem flags.

To enable automatic ADHD mode for all future sessions:

mkdir -p ~/.claude
touch ~/.claude/.i-have-adhd-always

To permanently disable the automatic injection:

rm ~/.claude/.i-have-adhd-always

To temporarily disable ADHD mode for a single active session, simply send the command:

stop adhd mode

Summary

• The SessionStart hook is registered in hooks/hooks.json with a matcher pattern covering startup, resume, clear, and compact events.
• The always-on.mjs script checks for ~/.claude/.i-have-adhd-always before proceeding, ensuring opt-in behavior.
• Upon validation, the script strips YAML front-matter from skills/i-have-adhd/SKILL.md and outputs the ruleset to stdout, which Claude renders as the first assistant message.
• Error handling guarantees the hook exits cleanly without blocking session startup if files are missing or inaccessible.
• Users control activation through filesystem flags and can deactivate per-session using the "stop adhd mode" command.

Frequently Asked Questions

What triggers the SessionStart hook in i-have-adhd?

The hook triggers on four specific session events: startup, resume, clear, and compact. This coverage ensures the ADHD ruleset injects whether you are starting a fresh conversation, restoring a previous context, clearing chat history, or compacting message threads.

How does the hook know whether to inject the ADHD rules?

The always-on.mjs script performs a filesystem check for the presence of .i-have-adhd-always in the Claude configuration directory (default ~/.claude/). If this flag file is absent, the script exits immediately without producing output, leaving the session in its default state.

What happens if the always-on script fails during execution?

The script implements comprehensive error handling that catches exceptions and exits with status code 0 regardless of failure type. This fail-safe design ensures that filesystem permission errors, missing SKILL.md files, or read errors never block or delay your Claude session startup.

How do I temporarily disable ADHD mode for a single session?

While the always-on flag remains in place for future sessions, you can disable ADHD mode for the current conversation by typing "stop adhd mode". This command instructs the plugin to cease applying the formatting rules for the remainder of that specific session without removing the permanent opt-in flag.

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