How Always-On Hooks Work in i-have-adhd: Implementation and Event Triggers

Always-on hooks in the i-have-adhd plugin execute automatically at every plugin initialization across supported AI runtimes, using platform-specific scripts declared in hooks/hooks.json to register skills and synchronize the environment.

The i-have-adhd repository implements a cross-platform plugin system designed to enhance AI interactions with ADHD-friendly formatting rules. At the core of this system lies the always-on hook architecture, which ensures the plugin activates immediately when loaded by any supported runtime, including OpenCode, Claude, Codex, Pi, OMP, Qwen, Kimi, and Gemini.

Architecture of the Always-On Hook System

The hooks.json Manifest

The entry point for the always-on behavior resides in hooks/hooks.json. This declarative manifest registers the always-on entry points with the runtime engine. The JSON structure maps the always-on hook name to three platform-agnostic scripts:

{
  "always-on": [
    "hooks/always-on.sh",
    "hooks/always-on.ps1",
    "hooks/always-on.mjs"
  ]
}

The runtime recognizes the always-on key as a built-in lifecycle hook that executes automatically during plugin initialization, making it the earliest hook available in the lifecycle.

Platform-Specific Script Implementations

The system provides three implementations to cover Unix-like systems, Windows PowerShell environments, and Node.js runtimes:

• hooks/always-on.sh – Bash implementation for Unix-like shells that prints a greeting and loads the skill markdown
• hooks/always-on.ps1 – PowerShell script for Windows-based runtimes providing equivalent functionality
• hooks/always-on.mjs – ES module for Node-based runtimes (OpenCode, Claude, Codex) that imports the skill definition and registers with the plugin manager

Each script performs identical initialization logic adapted to its execution environment.

What Events Trigger Always-On Hooks

Plugin Initialization

The primary trigger occurs once per plugin initialization, specifically when the runtime imports the plugin or starts a new session. This represents the earliest available hook point, guaranteeing the plugin's code executes before any user-invoked commands. The hook runs when any supported runtime (OpenCode, Claude, Codex, Pi, OMP, Qwen, Kimi, or Gemini) loads the i-have-adhd plugin.

Runtime and Manual Reload Events

The hook also triggers during:

• Runtime reload events – When the runtime reloads its plugin cache after code changes
• Manual plugin reloads – When users explicitly request a plugin reload via CLI commands

In both scenarios, the always-on hook re-executes to ensure the latest version of the skill remains active.

Internal Implementation Details

When executed, the always-on scripts perform several critical initialization tasks:

1. Load the skill definition from skills/i-have-adhd/SKILL.md
2. Synchronize the cursor-compatible mirror at .cursor/skills/i-have-adhd/SKILL.md
3. Register the 10 ADHD-friendly response rules with the runtime's skill manager
4. Emit optional logging output for test suite verification

Unix/Linux Execution Path

In hooks/always-on.sh, the Bash script handles environment setup for Unix-like systems, loading the skill markdown and initializing the skill mirror before the runtime processes user requests.

Windows Execution Path

The hooks/always-on.ps1 script provides equivalent functionality for PowerShell environments, ensuring Windows-based runtimes receive identical ADHD-friendly formatting capabilities.

Node.js Runtime Execution

The hooks/always-on.mjs ES module serves Node-based runtimes. It imports the skill definition from skills/i-have-adhd/SKILL.md and registers the plugin with the runtime's plugin manager, executing the same initialization sequence as its shell counterparts.

Testing and Verification

The repository includes tests/test_always_on_hooks.py to validate the always-on mechanism. This test suite spawns a temporary runtime, loads the plugin, and asserts that:

• The always-on scripts execute successfully
• Console output contains expected initialization markers
• The skill registration completes correctly

You can manually trigger the hook for testing purposes:

# Unix/Linux

bash hooks/always-on.sh

# Windows PowerShell

.\hooks\always-on.ps1

// Node.js environments
import './hooks/always-on.mjs';

Summary

• The always-on hook system uses hooks/hooks.json to declare entry points across three platform-specific scripts
• Triggers occur at plugin initialization, runtime reloads, and manual reloads across eight supported AI runtimes
• Each execution loads skill definitions from skills/i-have-adhd/SKILL.md, synchronizes cursor mirrors at .cursor/skills/i-have-adhd/SKILL.md, and registers 10 ADHD-friendly formatting rules
• Platform-specific implementations in .sh, .ps1, and .mjs ensure compatibility with Unix, Windows, and Node.js environments
• The tests/test_always_on_hooks.py file provides automated verification of hook execution

Frequently Asked Questions

What is the difference between always-on hooks and other hook types in i-have-adhd?

Always-on hooks execute automatically at plugin initialization without requiring user interaction, whereas other hook types (such as message-received or command-executed) respond to specific user actions or runtime events. The always-on mechanism handles only the initial setup and registration phase before any user commands are processed.

Why does i-have-adhd need three different script implementations?

The three implementations—always-on.sh, always-on.ps1, and always-on.mjs—ensure cross-platform compatibility across the diverse runtime environments supported. Bash serves Unix-like shells, PowerShell handles Windows platforms, and the ES module supports Node.js-based AI platforms like OpenCode, Claude, and Codex.

How can I verify that always-on hooks are executing correctly?

Run the test suite in tests/test_always_on_hooks.py, which validates hook execution by spawning a temporary runtime and checking for successful skill registration and expected console output. You can also manually execute the appropriate script for your platform from the repository root to observe the initialization sequence.

What happens if the always-on hook fails during initialization?

If the always-on hook fails, the skill registration and environment synchronization will not complete, potentially leaving the ADHD-friendly formatting rules unavailable. The runtime may log initialization errors, and the test suite's assertions in test_always_on_hooks.py would fail, indicating a setup problem that prevents the 10 response rules from being registered.

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