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

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, 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 at lines 63–67, it calls pi.registerFlag() with the identifier "adhd" and an options object defining the flag as a boolean.

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, the plugin invokes pi.registerCommand() with the command name "i-have-adhd" and an asynchronous handler.

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

# Enable ADHD mode for the current session at startup

pi --adhd

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

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

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 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, while context helpers reside in 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, 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.

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