How to Implement the SessionStart Hook in i-have-adhd: A Complete Guide

The i-have-adhd repository implements a SessionStart hook through hooks/hooks.json that registers three platform-specific scripts—always-on.sh, always-on.ps1, and always-on.mjs—to automatically inject ADHD coping rules whenever a new Claude session begins, contingent on an opt-in flag file at ~/.claude/.i-have-adhd-always.

The i-have-adhd skill for Claude uses a SessionStart hook to automatically apply its cognitive accessibility ruleset at the beginning of every new session. This hook architecture ensures users with ADHD receive consistent support without manually invoking commands each time. According to the source code in ayghri/i-have-adhd, the implementation relies on a JSON registry and three platform-specific scripts that check for an opt-in flag before injecting the rules.

Understanding the SessionStart Hook Architecture

The SessionStart hook follows a declarative registration pattern. When a compatible agent initializes a new session, it reads the hook registry and executes the appropriate script for the current operating system.

The hooks.json Registration File

The entry point for the SessionStart hook is hooks/hooks.json, which maps the session_start event to the implementation scripts:

{
  "session_start": [
    "hooks/always-on.sh",
    "hooks/always-on.ps1",
    "hooks/always-on.mjs"
  ]
}

This configuration tells the agent to execute the appropriate script during session startup. The agent selects the script based on the available runtime environment—POSIX shells, PowerShell, or Node.js.

Platform-Specific Implementation Scripts

The repository provides three functionally equivalent implementations to ensure cross-platform compatibility:

• hooks/always-on.sh: POSIX-compliant shell script for Linux and macOS environments.
• hooks/always-on.ps1: PowerShell script for Windows environments using Test-Path and Get-Content.
• hooks/always-on.mjs: Node.js ES module for environments where Node is available but native shell execution is restricted.

How the SessionStart Hook Works

Each script follows an identical four-step execution flow defined in the source code. When the agent triggers the session_start event, the selected script performs the following operations:

1. Checks for the opt-in flag at $CLAUDE_CONFIG_DIR/.i-have-adhd-always (defaulting to ~/.claude/.i-have-adhd-always). If absent, the script exits silently with status 0.
2. Resolves the ruleset path by locating skills/i-have-adhd/SKILL.md relative to the script's directory.
3. Strips YAML front-matter from the markdown file using regex patterns to isolate the usable content.
4. Outputs the ruleset to the session console, prefixed with the banner ADHD MODE ACTIVE (always‑on).

The hook is intentionally non-blocking. If the script encounters any error—such as missing files or permission issues—it exits with status 0 to prevent disrupting the session initialization.

Enabling and Disabling the SessionStart Hook

Users control the hook through a simple file-based toggle mechanism.

Permanent Activation (Always-On Mode)

To enable the SessionStart hook for all future sessions, create the opt-in flag file:

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

After creating this file, restart your Claude client. The hook will automatically execute at the start of every subsequent session, injecting the ADHD ruleset without manual intervention.

One-Off Session Usage

For temporary activation without enabling the permanent hook, use the slash command:

/i-have-adhd

This applies the ruleset to the current session only and does not create the flag file, leaving the SessionStart hook disabled for future sessions.

Disabling the Hook

To permanently disable the automatic injection, remove the flag file:

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

Subsequent sessions will start without the ADHD ruleset unless manually invoked via the slash command.

Core Files and Implementation Details

The SessionStart hook implementation spans several key files in the repository:

File	Purpose
hooks/hooks.json	Registers the session_start event handlers
hooks/always-on.sh	POSIX shell implementation
hooks/always-on.ps1	PowerShell implementation
hooks/always-on.mjs	Node.js ESM implementation
skills/i-have-adhd/SKILL.md	Source ruleset injected by the hook
tests/test_always_on_hooks.py	Test suite validating hook behavior

In hooks/always-on.sh, the core logic checks for the configuration directory and outputs the ruleset:

# Check for opt-in flag

if [ ! -f "$CLAUDE_CONFIG_DIR/.i-have-adhd-always" ]; then
    exit 0
fi

# Resolve and output ruleset (simplified)

echo "ADHD MODE ACTIVE (always-on)"
cat "$SCRIPT_DIR/../skills/i-have-adhd/SKILL.md"

Summary

• The SessionStart hook in i-have-adhd automatically injects ADHD coping strategies at the start of each Claude session.
• Registration occurs in hooks/hooks.json, which maps the session_start event to three platform-specific scripts.
• The hook requires an opt-in flag file at ~/.claude/.i-have-adhd-always to activate.
• Implementations exist for POSIX (always-on.sh), PowerShell (always-on.ps1), and Node.js (always-on.mjs) environments.
• The hook is non-blocking and exits with status 0 to prevent session initialization failures.

Frequently Asked Questions

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

The hook triggers automatically when a compatible agent (such as Claude) initializes a new session and reads the hooks/hooks.json file. The agent executes the appropriate platform-specific script from the session_start array, which then checks for the .i-have-adhd-always flag file before injecting the ruleset.

Can I use the SessionStart hook on Windows?

Yes. The repository includes hooks/always-on.ps1, a PowerShell implementation that mirrors the POSIX logic using Test-Path and Get-Content commands. Windows users with PowerShell enabled will have the hook executed automatically during session startup, provided the opt-in flag file exists.

Why does the SessionStart hook exit with status 0 even when disabled?

The hook is designed to be non-blocking. When the opt-in flag file is missing or when errors occur (such as inability to read SKILL.md), the scripts deliberately exit with status 0. This design prevents the session initialization from failing due to hook-related issues, ensuring the agent remains usable regardless of the skill's configuration state.

How do I verify the SessionStart hook is working correctly?

After enabling the hook by creating ~/.claude/.i-have-adhd-always, start a new Claude session. You should see the banner "ADHD MODE ACTIVE (always-on)" followed by the ruleset content from skills/i-have-adhd/SKILL.md. The repository includes tests/test_always_on_hooks.py for automated validation of this behavior.

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