# How the i-have-adhd Extension Registers Commands and Flags in the Pi/OMP API

> Learn how the i-have-adhd extension registers commands and flags in the Pi/OMP API using pi.registerFlag and pi.registerCommand for seamless state synchronization.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-19

---

**The i-have-adhd extension registers a boolean flag named `adhd` via `pi.registerFlag()` and a slash-command `/i-have-adhd` via `pi.registerCommand()` inside its main entry point in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), then synchronizes state across sessions using `pi.on()` event hooks.**

The `i-have-adhd` extension is a standard plugin for the Pi/OMP coding-agent runtimes, developed in the `ayghri/i-have-adhd` repository. When loaded, the default-exported `iHaveAdhdExtension` function receives an `ExtensionAPI` instance—commonly named `pi`—that exposes methods for extending both the Node-based Pi CLI and the browser-based OMP interface. Understanding how this extension registers commands and flags in the Pi/OMP API reveals the pattern used to add configurable, stateful behavior to the agent.

## Registering the `adhd` Flag via `registerFlag`

The extension first declares a configuration flag that users can set at startup or in a session file. In [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) at lines 63–67, it calls `pi.registerFlag()` with the identifier `"adhd"` and an options object defining the flag as a boolean.

```typescript
pi.registerFlag("adhd", {
  description: "Start with ADHD-friendly output enabled",
  type: "boolean",
  default: false,
});

```

This registration makes `--adhd` available on the Pi CLI and stores the value in the session context. Because the flag defaults to `false`, ADHD-friendly output is opt-in unless explicitly enabled by the user or restored from a previous session state.

## Registering the `/i-have-adhd` Command via `registerCommand`

After the flag, the extension adds an interactive slash-command that toggles the mode at runtime. At lines 69–91 of [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), the plugin invokes `pi.registerCommand()` with the command name `"i-have-adhd"` and an asynchronous handler.

```typescript
pi.registerCommand("i-have-adhd", {
  description: "Toggle ADHD-friendly output for this session",
  handler: async (args, ctx) => {
    const argument = args.trim().toLowerCase();
    if (argument === "") { setEnabled(!enabled, ctx); return; }
    if (argument === "on")  { setEnabled(true,  ctx); return; }
    if (argument === "off" || argument === "stop") { setEnabled(false, ctx); return; }
    ctx.ui.notify("Usage: /i-have-adhd [on|off]", "warning");
  },
});

```

The handler parses optional string arguments—`on`, `off`, `stop`, or empty—and calls the internal `setEnabled` helper to update the session state. When the argument is empty, the command acts as a toggle, flipping the current state before returning.

## Synchronizing State with Pi/OMP Event Hooks

Registration alone does not persist or react to session changes. To keep the UI status accurate and the ruleset injected, the extension attaches four event hooks through `pi.on()` immediately after registering the flag and command. These hooks are implemented in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) at lines 93–122.

- **input** – Intercepts user phrases such as "stop adhd mode" and disables the feature automatically.
- **session_start** – Restores the saved ADHD state when a new session begins, respecting the `adhd` flag or an always-on file if present.
- **session_tree** – Re-applies the saved state when the session tree changes.
- **session_compact** – Re-injects the ADHD-friendly ruleset after context compaction so the instructions are not lost.

Together, these hooks ensure that `registerFlag` and `registerCommand` behave consistently across the Pi and OMP runtimes, even as the session context evolves.

## Using the Flag and Command in Practice

You can enable ADHD-friendly output before the session starts or toggle it interactively.

Start a Pi session with the flag enabled from the CLI:

```bash

# Enable ADHD mode for the current session at startup

pi --adhd

```

Toggle the mode mid-session with the slash-command:

```bash

# Toggle ADHD-friendly output

pi /i-have-adhd

# Explicitly turn it on or off

pi /i-have-adhd on
pi /i-have-adhd off

```

Another extension can query or manipulate the state programmatically through the same `ExtensionAPI`:

```typescript
import { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function myExtension(pi: ExtensionAPI) {
  // Query the current state
  const adhdEnabled = pi.getFlag("adhd"); // true | false

  // Toggle it
  pi.executeCommand("i-have-adhd", adhdEnabled ? "off" : "on");
}

```

This pattern demonstrates how the Pi/OMP API exposes a unified surface for flags, commands, and hooks across both server and client environments.

## Summary

- The extension entry point in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) exports `iHaveAdhdExtension`, which receives the `pi` (`ExtensionAPI`) object on load.
- It registers the **`adhd`** boolean flag with `pi.registerFlag()` at lines 63–67, exposing a `--adhd` CLI option.
- It registers the **`/i-have-adhd`** slash-command with `pi.registerCommand()` at lines 69–91, accepting `on`, `off`, `stop`, or empty arguments.
- It attaches **`input`**, **`session_start`**, **`session_tree`**, and **`session_compact`** hooks via `pi.on()` at lines 93–122 to persist state and manage the ruleset lifecycle.
- The ruleset itself lives in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), while context helpers reside in [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts).

## Frequently Asked Questions

### How do I enable ADHD-friendly output when starting Pi?

Pass the `--adhd` flag on the command line. The extension registered this flag with `pi.registerFlag("adhd", { type: "boolean", default: false })` in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), so Pi recognizes it at startup and stores the value in the session context.

### What arguments does the `/i-have-adhd` command accept?

The command handler defined in `pi.registerCommand()` accepts `on`, `off`, `stop`, or an empty string. An empty string toggles the current state, while `off` or `stop` explicitly disables ADHD-friendly output. Any other input triggers a warning notification showing the usage syntax.

### Why does the extension need session hooks after registering the command and flag?

The hooks—`input`, `session_start`, `session_tree`, and `session_compact`—keep the plugin state synchronized with the conversation context. Without them, enabling ADHD mode would not survive context compaction or tree changes, and natural-language stop phrases would not be intercepted.

### Can other extensions read or change the ADHD state?

Yes. Any extension with access to the `ExtensionAPI` can call `pi.getFlag("adhd")` to read the boolean state and `pi.executeCommand("i-have-adhd", "off")` to change it, as shown in the programmatic example from the `ayghri/i-have-adhd` source code.