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

The 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 automatically at the beginning of relevant sessions. The hook is declared in hooks/hooks.json under the SessionStart event, which triggers on commands such as startup, resume, clear, and compact.

When activated, Claude Code runs:

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:

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:

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

The 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:

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.

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:

# Enable always-on mode

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

To permanently disable the feature, remove the flag file:

# 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 ./hooks/always-on.sh

Summary

• hooks/hooks.json registers 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, 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, 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 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.

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