How i-have-adhd Integrates with Pi and OMP Native Extensions: A Runtime-Agnostic Implementation

i-have-adhd provides a single TypeScript extension that registers flags, commands, and session hooks through the ExtensionAPI contract to enable ADHD-friendly output consistently across both Pi and OMP runtimes.

The ayghri/i-have-adhd repository delivers a unified native extension designed to work identically with both the Pi Coding Agent and Open-Code Multi-Platform (OMP) environments. By leveraging the runtime-agnostic ExtensionAPI from @earendil-works/pi-coding-agent, the extension ensures that ADHD-friendly behavior remains synchronized across sessions regardless of which runtime hosts the interaction.

Single Extension Architecture for Dual Runtime Support

Both runtimes load the identical extension file declared in opencode.json. When the runtime entry point imports extensions/i-have-adhd.ts, it injects an ExtensionAPI instance (pi) that exposes the same surface area for both Pi and OMP. This design guarantees that behavior updates apply automatically to both platforms without code duplication.

The extension logic resides in extensions/i-have-adhd.ts while helper utilities for session inspection live in extensions/context-compat.ts. The actual rule text is stored in skills/i-have-adhd/SKILL.md and loaded at runtime via the loadRules() function.

Registering CLI Flags and Slash Commands

The extension registers a boolean flag and a toggle command through the ExtensionAPI. The implementation calls pi.registerFlag("adhd", …) with a default value of false, exposing the --adhd CLI option in both Pi and OMP environments.

For interactive control, the extension calls pi.registerCommand("i-have-adhd", { … }) to bind the slash command. Users can execute:

/i-have-adhd       # toggles current state

/i-have-adhd on   # forces enable

/i-have-adhd off  # forces disable

Session Lifecycle and State Persistence

State management relies on the session-tree mechanism common to both runtimes. When users toggle the mode, the extension calls pi.appendEntry(STATE_ENTRY_TYPE, { enabled }) to persist the configuration.

The extension listens to three critical lifecycle events via pi.on("session_start"), pi.on("session_tree"), and pi.on("session_compact"). These hooks trigger restoreState and syncContext functions to re-inject rules or display disabled notices after compaction or restarts.

Dynamic Rule Injection and Input Processing

When enabled and the rules are not already present, the extension calls pi.sendMessage({ customType: RULES_MESSAGE_TYPE, … }) to inject the content from skills/i-have-adhd/SKILL.md into the model's context. OMP forwards these custom messages identically to Pi, ensuring the rule set reaches the LLM.

Input handling occurs through pi.on("input", …), which monitors for phrases like "stop adhd mode" or "normal mode" to automatically disable the mode via natural language.

UI Feedback and Cross-Platform Consistency

Both runtimes consume the same UI API calls. The extension uses ctx.ui.setStatus to display an "ADHD ON" status badge and ctx.ui.notify to send toast messages. OMP surfaces these in its console or IDE plugins exactly as Pi renders them in its interface.

Key Implementation Files

• extensions/i-have-adhd.ts: Core native-extension code that registers flags, commands, and session hooks for both runtimes.
• extensions/context-compat.ts: Utilities to read the session context and determine whether rules or disabled markers are active.
• skills/i-have-adhd/SKILL.md: Markdown file containing the ADHD-friendly rule set injected into the model's context.
• opencode.json: Declares the extension for both Pi and OMP runtimes, ensuring the same file loads on each platform.
• hooks/hooks.json: Registers the extension's hooks for automatic activation during session startup or compaction.

CLI Usage Examples

Start a session with ADHD mode enabled:

# Pi runtime

pi run --adhd

# OMP runtime

omp start --adhd

Programmatic access via the ExtensionAPI:

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

export default function myPlugin(pi: ExtensionAPI) {
  // Enable ADHD mode for the current session
  pi.sendMessage(
    { customType: "i-have-adhd-rules", content: "ADHD MODE ACTIVE …", display: false },
    { triggerTurn: false },
  );
}

Summary

• A single TypeScript extension serves both Pi and OMP runtimes through the ExtensionAPI contract.
• State persists across conversation turns using the session-tree mechanism via pi.appendEntry.
• Rules are dynamically injected from skills/i-have-adhd/SKILL.md when the mode is enabled.
• Both runtimes support identical CLI flags (--adhd), slash commands (/i-have-adhd), and UI feedback APIs.
• Natural language phrases like "stop adhd mode" automatically trigger mode deactivation.

Frequently Asked Questions

What is the ExtensionAPI contract and how does it enable cross-runtime compatibility?

The ExtensionAPI is defined in @earendil-works/pi-coding-agent and provides a runtime-agnostic interface for registering flags, commands, and event hooks. Both Pi and OMP implement this contract, allowing extensions/i-have-adhd.ts to execute identical code paths regardless of the host environment.

How does i-have-adhd persist state between conversation turns?

The extension calls pi.appendEntry(STATE_ENTRY_TYPE, { enabled }) to write the current mode state into the session tree. Because both runtimes share this session-tree mechanism, the boolean value survives across turns, restarts, and compaction events via the restoreState logic.

Can users disable ADHD mode using natural language instead of slash commands?

Yes. The extension binds an input hook via pi.on("input", …) that scans for phrases such as "stop adhd mode" or "normal mode". When detected, the extension automatically toggles the state off without requiring the explicit /i-have-adhd off command.

Which files contain the core integration logic for Pi and OMP?

The primary integration logic resides in extensions/i-have-adhd.ts, which is loaded by both runtimes. Helper functions for context inspection are in extensions/context-compat.ts, while the behavioral rules injected into the LLM context are stored in skills/i-have-adhd/SKILL.md.

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