# How the hooks/always-on.sh Mechanism Works in i-have-adhd

> Understand how the hooks always on.sh mechanism works in i have adhd. Learn how to inject rulesets into Claude Code responses by creating an opt-in flag file.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-08-02

---

**The [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh) script is a SessionStart hook that automatically injects the i-have-adhd ruleset into every Claude Code response when the user creates an opt-in flag file at `~/.claude/.i-have-adhd-always`.**

The `ayghri/i-have-adhd` repository provides a Claude Code plugin that optimizes AI output for ADHD cognitive styles. The always-on mechanism ensures these formatting rules persist across sessions without manual activation, operating through a lightweight POSIX shell script that integrates with Claude Code's hook system.

## Hook Registration and Session Start

Claude Code executes [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.sh) automatically at the beginning of relevant sessions. The hook is declared in **[`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json)** under the `SessionStart` event, which triggers on commands such as `startup`, `resume`, `clear`, and `compact`.

When activated, Claude Code runs:

```sh
sh "${CLAUDE_PLUGIN_ROOT}/hooks/always-on.sh"

```

During execution, the user sees the status message **"Checking i-have-adhd always-on flag…"** while the script determines whether to inject the ruleset.

## Opt-In Flag Detection

The script implements an explicit opt-in model to prevent unwanted behavior. It first determines the Claude configuration directory by checking `$CLAUDE_CONFIG_DIR`, falling back to `$HOME/.claude` if the variable is unset.

The script then constructs the path to the flag file:

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

```

If **`$flag_path`** does not exist, the script exits silently with code `0`, leaving the session unchanged. This design ensures zero overhead for users who have not enabled the feature.

## Locating and Parsing the Skill Definition

Once the opt-in flag is confirmed, the script locates the skill definition relative to its own execution path. Using `dirname` on `$0`, it resolves the path to **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)**:

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

```

The [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file contains YAML front-matter metadata delimited by `---` lines. The script strips this metadata using an `awk` pipeline to extract only the human-readable ruleset body:

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

```

This extraction ensures that only the actionable formatting rules—not the metadata—are injected into the conversation context.

## Injecting the Ruleset into Responses

Finally, the script outputs a banner followed by the extracted ruleset. This output is captured by Claude Code and prepended to the response stream, effectively applying ADHD-optimized formatting to every subsequent reply in the session.

```sh
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"

```

Users can disable the mode temporarily for the current session by issuing the command **"stop adhd mode"**, or permanently by deleting the flag file.

## Enabling and Disabling Always-On Mode

To activate the always-on behavior, create the opt-in flag file:

```sh

# Enable always-on mode

touch "$HOME/.claude/.i-have-adhd-always"

```

To permanently disable the feature, remove the flag file:

```sh

# Disable always-on mode

rm -f "$HOME/.claude/.i-have-adhd-always"

```

For debugging or manual invocation without restarting Claude Code, run the script directly from the repository root:

```sh
sh ./hooks/always-on.sh

```

## Summary

- **[`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json)** registers [`always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/always-on.sh) as a `SessionStart` hook, executing on session startup and resume commands.
- The script checks for **`~/.claude/.i-have-adhd-always`** (or `$CLAUDE_CONFIG_DIR/.i-have-adhd-always`) and exits silently if the opt-in flag is absent.
- Upon confirmation, it loads **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)**, strips the YAML front-matter using `awk`, and injects the ruleset into the response stream.
- The mechanism is fully POSIX-compliant, fails gracefully when files are missing, and allows temporary disabling via the "stop adhd mode" command.

## Frequently Asked Questions

### What triggers the always-on.sh hook to execute?

The hook executes during Claude Code `SessionStart` events, which include the `startup`, `resume`, `clear`, and `compact` commands. This registration is defined in [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json), ensuring the script runs automatically whenever a new session begins or an existing session is reset.

### How do I disable always-on mode temporarily versus permanently?

To disable the mode for the current session only, type **"stop adhd mode"** in the conversation. To disable it permanently, delete the opt-in flag file at `~/.claude/.i-have-adhd-always` (or wherever your `$CLAUDE_CONFIG_DIR` is set). Removing the file prevents the hook from injecting the ruleset in future sessions.

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

If the script cannot locate [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) relative to the hook's directory, it exits gracefully with code `0` without printing any output. This silent failure ensures that broken installations or moved files do not produce error messages or disrupt the Claude Code session.

### Is the always-on.sh script portable across different shell environments?

Yes, the script is written for POSIX-compliant shells (`/bin/sh`) and uses only standard utilities like `awk`, `dirname`, and `printf`. It avoids bash-specific features, ensuring compatibility across macOS, Linux, and other Unix-like systems where Claude Code might run.