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

> Discover how always-on hooks operate across Bash, PowerShell, and other shells. Learn how adapters source hooks.json for automatic command registration at session startup.

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

---

**Always-on hooks in the i-have-adhd repository work through thin shell-specific adapters that source a central [`hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`:

```bash

# Load i-have-adhd always-on hooks

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

```

The `source` command executes [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/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`:

```powershell

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

```javascript
// 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`](https://github.com/ayghri/i-have-adhd/blob/main/hooks.json) Drives Cross-Shell Consistency

All three adapters read from **[`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) | Central declarative configuration for all hooks |
| [`hooks/always-on.sh`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.