Pi and OMP Extension APIs in i-have-adhd: Key Differences and Code Examples

The i-have-adhd repository exposes two runtime-specific extension APIs—Pi and OMP—that adapt the same core skill logic to different AI execution environments through distinct entry points, payload shapes, and error-handling contracts.

The ayghri/i-have-adhd project ships dual extensions so the skill can run on both the Pi runtime and the OMP (Open Meta Prompt) runtime. While both routes ultimately invoke the logic defined in skills/i-have-adhd/SKILL.md, they present incompatible surface APIs that require separate TypeScript entry points. Understanding these differences is essential when integrating or testing against either platform.

Pi Extension API

The Pi extension targets the Pi AI execution environment with a minimal, direct function signature.

Source File and Exported Contract

The Pi implementation lives in extensions/i-have-adhd.ts. It exports a default async function that receives a Pi-specific request object and returns a raw string response.

// extensions/i-have-adhd.ts
export default async function (payload: PiPayload): Promise<string>

The Pi runtime invokes this default export directly after reading the pi field in package.json. Tests for this path import the default export and pass a flat payload object.

Request Shape and Error Handling

The Pi API receives a flat payload containing the user message and top-level metadata. The skill can access these fields without traversal or transformation.

const piPayload = {
  userMessage: 'Help me stay focused',
  metadata: { userId: '1234' }
};

Error handling is implicit: the function throws native JavaScript errors, and the Pi runtime surfaces those as failure responses. There is no standardized error envelope.

OMP Extension API

The OMP extension provides a compatibility layer for contexts that the OMP runtime expects.

Compatibility Shim and Handler

The OMP entry point is extensions/context-compat.ts. Instead of a default export, it exposes a named handler that conforms to OMP’s Context interface.

// extensions/context-compat.ts
export const handler = async (ctx: OMPContext): Promise<OMPResponse> => { … }

The OMP runtime loads the module via the omp field in package.json and calls the exported handler. Test suites import handler directly and feed it a mock OMP context.

Context Object and Response Contract

Unlike the flat Pi payload, the OMP handler receives a richer Context object that may contain nested session data. The compatibility shim flattens this structure before passing it to the core skill logic.

const ompContext = {
  request: { text: 'Help me stay focused' },
  session: { userId: '1234' },
  // additional OMP-specific fields …
};

Error handling follows a standardized contract. The handler returns an OMPResponse object that includes status and error fields rather than throwing exceptions.

Runtime Configuration

The repository declares runtime-specific entry points inside package.json. The Pi runtime uses the pi field to locate extensions/i-have-adhd.ts, while the OMP runtime uses the omp field to declare extensions/context-compat.ts. These entries ensure the correct module loads for each target environment without manual path resolution.

Practical Code Examples

Calling the Pi Extension

import runPi from '../extensions/i-have-adhd.ts';

const piPayload = {
  userMessage: 'Help me stay focused',
  metadata: { userId: '1234' }
};

runPi(piPayload).then(response => {
  console.log('Pi response:', response);
});

Calling the OMP Extension

import { handler } from '../extensions/context-compat.ts';

const ompContext = {
  request: { text: 'Help me stay focused' },
  session: { userId: '1234' },
  // additional OMP-specific fields …
};

handler(ompContext).then(ompResponse => {
  console.log('OMP response:', ompResponse.output);
});

Both snippets exercise the same underlying skill behavior but speak the protocol expected by their respective runtimes.

Summary

• extensions/i-have-adhd.ts exposes a default run function for the Pi runtime, accepting a flat PiPayload and returning a Promise<string>.
• extensions/context-compat.ts exposes a named handler for the OMP runtime, accepting a nested OMPContext and returning a structured OMPResponse.
• The Pi API throws native errors; the OMP API returns standardized error objects via its response envelope.
• Both extensions route to the canonical skill definition in skills/i-have-adhd/SKILL.md.
• Runtime selection is driven by the pi and omp fields in package.json.

Frequently Asked Questions

What is the main source file for the Pi extension API?

The Pi extension API is implemented in extensions/i-have-adhd.ts. This file defines the default async export that the Pi runtime invokes directly when it loads the skill.

How does error handling differ between the Pi and OMP extension APIs?

The Pi extension throws native JavaScript errors and lets the Pi runtime catch and surface them. The OMP extension returns an OMPResponse object containing explicit status and error fields, adhering to OMP’s standardized error contract.

Do both extension APIs share the same core skill implementation?

Yes. Both extensions/i-have-adhd.ts and extensions/context-compat.ts act as thin adapters that route to the same core logic defined in skills/i-have-adhd/SKILL.md. The extensions only differ in how they shape inputs and outputs for their respective runtimes.

Which runtime configuration fields declare the Pi and OMP entry points?

The repository’s package.json uses a pi field to declare the Pi entry point and an omp field to declare the OMP entry point. These fields tell each runtime which module to load and which exported symbol to execute.

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