# How the i-have-adhd Extension is Registered for Pi and OMP: A Technical Deep Dive

> Discover how the i-have-adhd extension registers with Pi and OMP. Learn about CLI flags, slash commands, and lifecycle hooks for managing ADHD guidance rules.

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

---

**The i-have-adhd extension registers for Pi and OMP runtimes by loading rule files and configuration, then exposing a CLI flag (`--adhd`), a slash command (`/i-have-adhd`), and lifecycle hooks that inject or retract ADHD guidance rules into the model context based on session state.**

The **ayghri/i-have-adhd** repository provides a toggleable ADHD-friendly mode for AI coding assistants. Understanding how the **i-have-adhd extension is registered for Pi and OMP** reveals a sophisticated pattern for runtime extension management, state persistence, and dynamic context manipulation.

## Extension Architecture and Registration Overview

Both **Pi** and **OMP** (Open-Multi-Platform) runtimes share an identical registration implementation because they consume the same `ExtensionAPI` contract. The registration process declared in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) initializes the extension by loading static resources, registering user interface elements, and binding event listeners to session lifecycle hooks.

The extension operates as a stateful middleware that intercepts session events to maintain a consistent ADHD-friendly context across conversation turns.

## Step-by-Step Registration Process

### Loading ADHD Rules and Configuration

Registration begins by loading the core rule set and optional user preferences. The `loadRules()` function reads [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), strips YAML frontmatter, and stores the raw rule text in memory. Simultaneously, `loadConfig()` attempts to parse [`i-have-adhd.json`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.json) for boolean flags including `alwaysOn` and `hideStatus`.

```typescript
// extensions/i-have-adhd.ts (Lines 42-49, 61-78)
const rules = await loadRules(); // Strips frontmatter from SKILL.md
const config = await loadConfig(); // Parses i-have-adhd.json

```

### CLI Flag and Slash Command Registration

The extension registers two primary user interaction surfaces:

- **`--adhd` Boolean flag**: Registered via `pi.registerFlag`, this forces the mode enabled at process startup
- **`/i-have-adhd` slash command**: Registered via `pi.registerCommand`, accepting `on`, `off`, or no arguments to toggle state at runtime

```typescript
// extensions/i-have-adhd.ts (Lines 81-109)
pi.registerFlag("adhd", "boolean", "Enable ADHD-friendly mode");
pi.registerCommand("/i-have-adhd", (args) => {
  // Handles on/off/toggle logic
});

```

### Session State Persistence

To maintain continuity across conversation sessions, the extension declares a `STATE_ENTRY_TYPE` constant and implements `getSavedState()`. This stores the enabled/disabled state in the session manager's custom entry storage, which is restored automatically during `session_start` or tree rebuild events.

The persistence mechanism ensures that users do not need to re-enable the mode manually when the context window refreshes or when resuming a previous session.

### UI Status Indicator Setup

When active, the extension calls `ctx.ui.setStatus` to display a green "● ADHD ON" badge in the interface. The `updateStatus()` function respects the `hideStatus` configuration flag, allowing users to suppress the visual indicator while retaining the functional behavior.

### Context Injection and Lifecycle Hooks

The core registration culminates in binding to three critical lifecycle events:

1. **`session_start`**: Restores saved state and syncs context
2. **`session_tree`**: Handles context tree rebuilds
3. **`session_compact`**: Manages context compression events

The `syncContext()` function determines whether to inject rules using `RULES_MESSAGE_TYPE` or retract them using `DISABLED_MESSAGE_TYPE`. It leverages `rulesAreInContext()`, which internally calls `latestMarkerIsActive()` from [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts) to check the current context state before modifying it.

```typescript
// extensions/i-have-adhd.ts (Lines 34-59)
if (enabled && !rulesAreInContext(ctx)) {
  pi.sendMessage({ customType: RULES_MESSAGE_TYPE, content: rules });
} else if (!enabled && rulesAreInContext(ctx)) {
  pi.sendMessage({ customType: DISABLED_MESSAGE_TYPE, content: "ADHD MODE OFF" });
}

```

## Runtime Behavior and Input Handling

Once registered, the extension monitors input events through a dedicated handler that processes:

- **Built-in skill aliases**: Recognizes `/skill:i-have-adhd` commands
- **Stop phrases**: Detects "stop adhd mode" or "normal mode" to automatically disable the feature
- **Confirmation messages**: Optionally returns `DISABLE_CONFIRMATION` when turning off via voice command

The input handler (Lines 111-134 in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)) acts as a secondary filtering layer that interprets natural language disable requests without requiring explicit slash command syntax.

## Code Examples

Enable ADHD mode at startup using the CLI flag:

```bash
pi --adhd

# or for OMP runtime

omp --adhd

```

Toggle mode dynamically within a session:

```typescript
// Toggle via slash command
await pi.runCommand("/i-have-adhd on");

// Check if extension is active programmatically
if (ctx.sessionManager.hasCustomEntry("i-have-adhd-state")) {
  console.log("ADHD mode is currently enabled");
}

```

Disable via natural language input:

```typescript
await pi.sendMessage({ text: "stop adhd mode" }); 
// Automatically triggers the disable handler and retracts rules

```

## Summary

- **Registration entry point**: [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) implements the `ExtensionAPI` contract for both Pi and OMP runtimes
- **Configuration loading**: Reads [`i-have-adhd.json`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.json) for `alwaysOn` and `hideStatus` flags while loading rules from [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)
- **User interfaces**: Exposes `--adhd` CLI flag and `/i-have-adhd` slash command for mode control
- **State management**: Persists enabled/disabled state using `STATE_ENTRY_TYPE` and restores via `getSavedState()` on session events
- **Context manipulation**: Injects `RULES_MESSAGE_TYPE` messages when enabled and `DISABLED_MESSAGE_TYPE` when disabled, checked via [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) utilities
- **Lifecycle integration**: Hooks into `session_start`, `session_tree`, and `session_compact` events to maintain consistent context

## Frequently Asked Questions

### How does the i-have-adhd extension detect whether to inject rules into the context?

The extension uses the `rulesAreInContext()` helper function, which calls `latestMarkerIsActive()` from [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts). This utility checks whether the most recent custom message marker indicates an active rules injection, preventing duplicate insertions or premature retractions.

### Can the i-have-adhd extension be enabled permanently without using the CLI flag?

Yes. Create an [`i-have-adhd.json`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.json) file in your project root with `{"alwaysOn": true}`. The `loadConfig()` function reads this during registration and automatically enables the mode for all sessions regardless of CLI arguments.

### What happens to the ADHD rules when the context window is compressed?

The extension listens to `session_compact` events and re-injects the rules if the mode remains enabled. Because state persists via `STATE_ENTRY_TYPE`, the `syncContext()` function ensures ADHD guidance remains present even after context tree optimization occurs.

### Is the registration process identical between Pi and OMP runtimes?

Yes. Both runtimes use the same `ExtensionAPI` contract, so [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) registers identically for Pi and OMP. The `.opencode/plugins/i-have-adhd.mjs` entry point adapts the same TypeScript implementation for the OpenCode runtime with no logic changes.