Always-On Hooks in i-have-adhd: How Automatic ADHD Ruleset Injection Works

The always-on hooks located at hooks/always-on.mjs automatically inject the ADHD response ruleset into every Claude Code session upon startup, requiring explicit user opt-in via a flag file to ensure consent-based activation.

The ayghri/i-have-adhd repository provides Claude Code extensions designed to optimize AI interactions for users with attention differences. The always-on hooks serve as the automated entry point that conditionally prepends these behavioral guidelines to every model response, ensuring consistent application without manual activation.

Hook Architecture and Execution Context

The always-on hook is implemented as a modern Node.js module that executes directly within the Claude Code runtime environment. Unlike platform-specific shell scripts, this approach guarantees consistent behavior across macOS, Linux, and Windows systems. According to the source comments in hooks/always-on.mjs (lines 5-9), the Claude/Codex plugin infrastructure launches this hook automatically at the start of every new session, establishing it as a persistent middleware layer.

Step-by-Step Execution Flow

The hook operates through six distinct phases that prioritize user consent and system stability.

Environment Detection and Compatibility

Written in ES module syntax, the hook leverages Node.js filesystem APIs to ensure cross-platform compatibility. It executes as part of the shared Claude Code/Codex plugin system, eliminating dependencies on external shell environments or operating system-specific binaries.

Opt-In Verification

Before loading any rules, the hook verifies explicit user consent by checking for a hidden flag file named .i-have-adhd-always. The script searches for this file within the Claude configuration directory, resolving either $CLAUDE_CONFIG_DIR or defaulting to ~/.claude (lines 15-21).

If the flag file does not exist, the hook exits immediately with status code 0, ensuring that session initialization proceeds without interruption or error messages. This design prevents accidental activation and respects user autonomy.

Ruleset Location and Validation

Upon confirming opt-in status, the hook resolves the canonical skill file path at skills/i-have-adhd/SKILL.md relative to its own location in the repository (lines 22-25). This path resolution strategy avoids reliance on tamper-prone environment variables, ensuring the hook loads the authentic ruleset from the expected location. If the skill file is missing, the hook again exits silently with status 0.

Content Processing and Cleanup

The script reads the entire skill file and performs critical sanitization steps (lines 27-34). It strips the YAML front-matter block—the content between the opening and closing --- delimiters—removing metadata headers that should not appear in the output. Additionally, it trims trailing blank lines to produce a clean text body containing only the 10 ADHD-friendly response rules.

Output Injection and User Notification

The processed rule text is written to standard output, prefixed with an explanatory banner (lines 36-40). This banner informs the user that ADHD MODE ACTIVE (always-on) is running and provides explicit instructions for temporary deactivation by typing "stop adhd mode" in the chat, or permanent deactivation by deleting the flag file. This ensures users retain full control even after initial activation.

Error Handling and Fail-Safe Design

The entire execution flow is wrapped in a comprehensive error handler (lines 41-44). Any unexpected exceptions—whether filesystem errors, permission issues, or parsing failures—trigger an immediate exit with status 0. This fail-safe behavior guarantees that the hook never blocks session startup, prioritizing system availability over feature activation.

Enabling and Disabling Always-On Mode

Users control the always-on hooks through simple filesystem operations.

To enable the feature permanently, create the opt-in flag file:

# Create the Claude config directory if it doesn't exist

mkdir -p ~/.claude

# Create the opt-in flag file

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

To disable the mode for a single session without removing the flag file, type the following command in the Claude chat interface:

stop adhd mode

To permanently disable the always-on functionality, delete the flag file:

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

When active, the hook produces output similar to:

ADHD MODE ACTIVE (always-on). The ruleset below applies to every response. 
"stop adhd mode" turns it off for this session; 
delete /home/username/.claude/.i-have-adhd-always to turn always-on off for good.

[Cleaned rule set content from SKILL.md appears here...]

Summary

• Always-on hooks reside at hooks/always-on.mjs and execute automatically at every Claude session start.
• Explicit opt-in is required via the .i-have-adhd-always flag file in the Claude configuration directory.
• Content sanitization removes YAML front-matter and formatting artifacts before injection.
• Fail-safe design ensures the hook exits cleanly with status 0 under all conditions, preventing session startup failures.
• User control is maintained through both temporary chat commands and permanent file deletion.

Frequently Asked Questions

What file triggers the always-on hook activation?

The hook activates only when it detects a hidden file named .i-have-adhd-always inside the Claude configuration directory, typically located at ~/.claude/.i-have-adhd-always. Without this explicit opt-in marker, the script exits silently and performs no injection.

Where does the hook source the ADHD rules from?

The hook resolves the ruleset from skills/i-have-adhd/SKILL.md relative to its own installation path. It specifically targets this canonical location to ensure it loads the complete, unmodified rule set directly from the repository structure.

How do I temporarily disable the always-on mode for a single session?

Type "stop adhd mode" into the Claude chat interface. This command disables the ruleset for the current conversation without deleting the permanent flag file, allowing you to resume always-on behavior in subsequent sessions.

What happens if the skill file is missing when the hook runs?

If skills/i-have-adhd/SKILL.md cannot be found, the hook exits immediately with status code 0. This silent failure ensures that missing resources never interrupt your ability to start a new Claude session, though the ADHD enhancements will not be active for that session.

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