How Always-On Hooks Operate Across Bash, PowerShell, and Other Shells

Always-on hooks in the i-have-adhd repository work through thin shell-specific adapters that source a central hooks.json configuration, automatically registering commands and environment variables at session startup.

The i-have-adhd project implements a cross-shell "always-on" system that ensures ADHD-focused productivity tools are consistently available regardless of your working environment. Instead of maintaining duplicate logic across platforms, the repository uses a single declarative configuration parsed by native shell adapters.

The Always-On Hook Architecture

The system centers on three platform-specific entry points in the hooks/ directory, each designed to integrate with native shell startup mechanisms.

Bash and POSIX Shells

Bash users load hooks/always-on.sh through standard shell sourcing. This adapter runs within the current shell environment, making functions and variables available for the entire session.

Add to ~/.bashrc, ~/.profile, or ~/.zshrc:

# Load i-have-adhd always-on hooks

source "/opt/i-have-adhd/hooks/always-on.sh"

The source command executes hooks/always-on.sh in the current process, preserving all exported definitions.

PowerShell

PowerShell uses hooks/always-on.ps1 with the call operator (&) to execute within the current session. Add to your $PROFILE:

# Load i-have-adhd always-on hooks

& "C:\Program Files\i-have-adhd\hooks\always-on.ps1"

The & operator ensures the script runs in the active session scope, enabling aliases and environment variables to persist.

Node-Based Runtimes

For JavaScript/TypeScript environments like the "Pi" or "OMP" adapters, hooks/always-on.mjs registers hooks through the runtime's extension API:

// Import the always-on module at startup
import "./hooks/always-on.mjs";

This module-based approach provides identical behavior without requiring shell-specific syntax.

How hooks.json Drives Cross-Shell Consistency

All three adapters read from hooks/hooks.json, the single source of truth for hook definitions. This JSON file contains declarative descriptions of:

• Hook names
• Commands to execute
• Platform-specific variations

The language-specific scripts parse this configuration and translate it into native shell syntax:

Source JSON	Bash output	PowerShell output
"env": {"VAR": "value"}	export VAR=value	$env:VAR = 'value'

This translation layer ensures identical behavior across ecosystems while respecting each shell's conventions.

Key Design Principles

The always-on hook system follows four architectural guidelines:

1. Single source of truth — All definitions live in hooks/hooks.json
2. Thin language adapters — Shell-specific wrappers handle syntax translation
3. Automatic loading — One profile line activates the entire system
4. Extensibility — New shells require only a new JSON-to-syntax adapter

Source Files Reference

File	Purpose
hooks/hooks.json	Central declarative configuration for all hooks
hooks/always-on.sh	Bash/POSIX adapter; sources definitions into current shell
hooks/always-on.ps1	PowerShell adapter; sets environment variables and aliases
hooks/always-on.mjs	Node.js module; registers hooks via runtime extension API

Summary

• Always-on hooks activate automatically at shell startup through profile configuration
• The hooks/ directory contains platform-specific adapters for Bash, PowerShell, and Node.js
• hooks.json serves as the unified configuration layer parsed by all adapters
• Each adapter translates JSON definitions into native shell commands (export, $env:, etc.)
• Adding support for additional shells requires only a new adapter that reads hooks.json

Frequently Asked Questions

What makes these hooks "always-on"?

The hooks execute automatically when a new shell session starts. Once you add the appropriate source or & command to your shell profile, every terminal window inherits the configured environment without manual intervention.

Can I use multiple shells simultaneously?

Yes. Each shell runs its own adapter process, but all read from the same hooks.json file. Changes to the central configuration propagate to all active shell types on their next startup.

How do I customize which hooks load?

Edit hooks/hooks.json directly. The declarative format allows adding, removing, or modifying hooks without touching adapter code. The shell-specific scripts rebuild their runtime environment from this file each session.

What happens if hooks.json contains syntax errors?

Adapter behavior varies by platform. Bash typically exits with an error message if JSON parsing fails. PowerShell may throw a terminating exception. Node-based runtimes report parse errors through the extension API. All adapters validate JSON before attempting to apply hook definitions.

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