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

> Learn to implement the SessionStart hook in i-have-adhd. This guide shows how to automate ADHD coping rules with platform-specific scripts for a seamless experience.

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

---

**The i-have-adhd repository implements a SessionStart hook through [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) that registers three platform-specific scripts—[`always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json), which maps the `session_start` event to the implementation scripts:

```json
{
  "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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```bash
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:

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) | Registers the `session_start` event handlers |
| [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | Source ruleset injected by the hook |
| [`tests/test_always_on_hooks.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_always_on_hooks.py) | Test suite validating hook behavior |

In [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh), the core logic checks for the configuration directory and outputs the ruleset:

```bash

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). The repository includes [`tests/test_always_on_hooks.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_always_on_hooks.py) for automated validation of this behavior.