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

> Explore Pi vs OMP extension APIs in i-have-adhd. Understand key differences in entry points, payloads, and error handling with practical code examples.

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

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts). It exports a **default async function** that receives a Pi-specific request object and returns a raw string response.

```ts
// 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`](https://github.com/ayghri/i-have-adhd/blob/main/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.

```ts
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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts). Instead of a default export, it exposes a named **`handler`** that conforms to OMP’s `Context` interface.

```ts
// 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`](https://github.com/ayghri/i-have-adhd/blob/main/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.

```ts
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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json). The **Pi** runtime uses the `pi` field to locate [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), while the **OMP** runtime uses the `omp` field to declare [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/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

```ts
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

```ts
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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md).
- Runtime selection is driven by the `pi` and `omp` fields in [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) and [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts) act as thin adapters that route to the same core logic defined in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.