# How the SessionStart Hook in `hooks/always-on.sh` Enables the i-have-adhd Skill on Startup

> Discover how SessionStart hook in hooks/always-on.sh enables the i-have-adhd skill on startup by injecting rules into the system prompt. Learn more now!

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: internals
- Published: 2026-07-22

---

**The SessionStart hook configured in [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) automatically executes [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh) at the beginning of every Claude Code session, injecting the i-have-adhd ruleset into the system prompt when it detects an opt-in flag file.**

The SessionStart hook mechanism allows Claude Code plugins to initialize context before any user interaction occurs. In the `ayghri/i-have-adhd` repository, this hook implements an "always-on" mode that applies ADHD-focused communication guidelines to every response without requiring manual skill activation commands.

## SessionStart Hook Registration in [`hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks.json)

Claude Code discovers the hook through the configuration file [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json), which registers a SessionStart event matcher:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/always-on.sh\"",
            "timeout": 5,
            "statusMessage": "Checking i-have-adhd always-on flag..."
          }
        ]
      }
    ]
  }
}

```

The matcher triggers on four session events—**startup**, **resume**, **clear**, and **compact**—ensuring the skill activates for new conversations and continued sessions alike. The hook executes [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh) with a five-second timeout, displaying a status message while processing.

## The Three-Step Activation Process

The [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh) script performs a conditional three-step validation to determine whether to inject the skill ruleset.

### Step 1: Detect the Opt-In Flag

The script first checks for the presence of a sentinel file in the Claude configuration directory:

```sh
claude_dir="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
flag_path="$claude_dir/.i-have-adhd-always"
[ -f "$flag_path" ] || exit 0

```

If `~/.claude/.i-have-adhd-always` does not exist, the script exits silently with code 0, leaving the session unchanged. Creating this empty file serves as the user's explicit opt-in signal to enable the SessionStart hook functionality.

### Step 2: Locate the Skill Description

After confirming the flag, the script resolves the relative path to the skill's canonical ruleset:

```sh
script_dir=$(dirname -- "$0")
skill_path="$script_dir/../skills/i-have-adhd/SKILL.md"
[ -f "$skill_path" ] || exit 0

```

This approach uses the script's own location (`$0`) to find [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) without relying on hardcoded absolute paths or additional environment variables. If the markdown file is missing, the hook aborts without error.

### Step 3: Strip Frontmatter and Output Rules

The script processes [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) to remove YAML frontmatter and inject the remaining content:

```sh
body=$(awk '
  NR == 1 && $0 ~ /^---[[:space:]]*$/ { in_fm = 1; next }
  in_fm && $0 ~ /^---[[:space:]]*$/   { in_fm = 0; next }
  !in_fm                              { print }
' "$skill_path") || exit 0
printf 'ADHD MODE ACTIVE (always-on). The ruleset below applies to every response. "stop adhd mode" turns it off for this session; delete %s to turn always-on off for good.\n\n%s\n' \
  "$flag_path" "$body"

```

The `awk` command filters out the metadata block between `---` delimiters, preserving only the actual rules. The script then prints a banner message followed by the cleaned ruleset, which Claude Code captures and inserts into the session's system prompt. This ensures the i-have-adhd constraints apply to **every** assistant response until explicitly disabled.

## Managing the Always-On Mode

Control the SessionStart hook behavior using these shell commands:

**Enable permanently (creates the opt-in flag):**

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

```

**Disable for the current session only:**

Type the following in the Claude chat:

```

stop adhd mode

```

**Disable permanently (removes the opt-in flag):**

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

```

**Debug the hook manually:**

```bash
sh "$(git rev-parse --show-toplevel)/hooks/always-on.sh"

```

## Summary

- The SessionStart hook in [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) triggers [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh) on every session startup, resume, clear, or compact event.
- The script checks for `~/.claude/.i-have-adhd-always` as an opt-in mechanism; without this file, the hook exits silently.
- Upon validation, the script reads [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), strips YAML frontmatter using `awk`, and injects the ruleset into the active session.
- The printed output includes instructions to disable the mode temporarily ("stop adhd mode") or permanently (delete the flag file).

## Frequently Asked Questions

### What triggers the SessionStart hook to run?

The hook executes when Claude Code detects specific session lifecycle events: **startup** (new conversation), **resume** (returning to existing conversation), **clear** (clearing conversation history), or **compact** (compressing long conversations). This ensures the i-have-adhd skill remains active across all session transitions.

### How do I disable the skill for just one session?

Type `stop adhd mode` in the chat input. This command disables the ADHD ruleset for the current session only, without deleting the `~/.claude/.i-have-adhd-always` flag file. The SessionStart hook will reactivate the skill the next time you start or resume a conversation.

### Where is the actual skill ruleset stored?

The canonical ruleset lives in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) relative to the repository root. The [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh) script reads this file, removes the YAML frontmatter block (delimited by `---`), and outputs the remaining content as the active ruleset for the session.

### What happens if the SKILL.md file is missing?

If [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh) cannot locate [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), it exits with code 0 immediately after the file check (`[ -f "$skill_path" ] || exit 0`). This silent failure prevents error messages from cluttering the session startup, though the skill will not activate despite the presence of the opt-in flag.