# What Is the Purpose of the context-compat.ts Extension and Why Is It Required for OMP?

> Understand the purpose of the context-compat.ts extension. Learn why it's essential for OMP and how it enables the i-have-adhd skill to read context messages across session managers.

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

---

**The [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) extension provides a runtime-agnostic compatibility layer that lets the *i-have-adhd* skill read context messages from any session manager, and it is specifically required for OMP because that runtime uses a different session-manager API than other runtimes.**

The *i-have-adhd* repository by ayghiri is an open-source skill designed to make AI interactions more ADHD-friendly through contextual response rules. To function across multiple runtimes, the skill must handle divergent session-manager interfaces without duplicating core logic. The [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) extension solves this problem by abstracting away runtime-specific differences.

## What context-compat.ts Actually Does

Located at [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts), this module exposes three key capabilities:

### The ContextMessageMarker Shape

```ts
// Represents custom context entries used by the skill
interface ContextMessageMarker {
  // Markers enable or disable ADHD-friendly response rules
}

```

This type definition captures the structure of metadata that controls focus-mode behaviors and other ADHD accommodations.

### The contextMessages() Function

```ts
import { contextMessages } from "./context-compat";

const markers = contextMessages(sessionManager);

```

The `contextMessages(sessionManager)` implementation safely extracts markers from session managers implementing either:

- `buildSessionContext()` — returns `{ messages: … }` (Pi runtime style)
- `buildContextEntries()` — returns an array of markers (OMP runtime style)

If neither method exists or execution throws, the function returns an empty array. This fallback prevents startup crashes when session managers lack expected APIs.

### The latestMarkerIsActive() Helper

```ts
const isActive = latestMarkerIsActive(
  markers,
  "focus_mode_active",
  "focus_mode_disabled"
);

```

This utility walks extracted markers to determine whether a specific rule is currently enabled, comparing the most recent activation and deactivation states.

## Why OMP Specifically Requires context-compat.ts

OMP (Open-Model Playground) implements `buildContextEntries()` exclusively. Other runtimes like Pi implement `buildSessionContext()`. Without the compatibility shim, the skill would need runtime-specific conditional branches throughout its codebase.

The OMP integration imports [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) to:

1. Eliminate runtime-detection logic from core skill code
2. Maintain a single source of truth for context-handling behavior
3. Ensure resilience when session manager APIs change

## Practical Usage Examples

### Extracting Markers in OMP-Based Extensions

```ts
import { contextMessages, latestMarkerIsActive } from "./context-compat";

// sessionManager injected by OMP at runtime
const markers = contextMessages(sessionManager);

const focusActive = latestMarkerIsActive(
  markers,
  "focus_mode_active",
  "focus_mode_disabled"
);

if (focusActive) {
  // Apply shortened responses, structured formatting, etc.
}

```

### Universal Fallback Handling

```ts
const markers = contextMessages(sessionManager);
// Works identically whether manager has buildSessionContext
// or buildContextEntries — no runtime checks needed

```

## Key Files in the Compatibility System

- **[`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts)** — Compatibility utilities for extracting and interpreting context markers
- **[`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)** — Main runtime extension importing [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) for OMP execution
- **[`scripts/check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_context_compat.ts)** — Validation script testing the layer across supported runtimes

## Summary

- The [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) extension abstracts session-manager API differences between runtimes
- OMP requires it because it uses `buildContextEntries()` instead of `buildSessionContext()`
- The module provides type safety, graceful degradation, and elimination of runtime-specific branches
- `contextMessages()` normalizes extraction; `latestMarkerIsActive()` interprets marker state
- This design keeps the *i-have-adhd* skill portable across Pi, OMP, and future runtimes

## Frequently Asked Questions

### What happens if a session manager has neither buildSessionContext nor buildContextEntries?

The `contextMessages()` function catches this condition and returns an empty array. This prevents runtime errors and lets the skill start normally, simply operating without context-aware features until a compatible session manager becomes available.

### Can context-compat.ts handle session managers that change their API between versions?

Yes. The defensive implementation checks for method existence before invocation and wraps calls in try-catch blocks. This resilience means the skill continues functioning even if upstream runtimes modify their session-manager interfaces.

### Is there a performance cost to using the compatibility layer?

Negligible. The abstraction performs at most two property lookups and a single method call per context extraction. The validation script at [`scripts/check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_context_compat.ts) confirms this overhead is undetectable in practice.

### Why not use runtime detection directly in the main skill code?

Doing so would scatter environment-specific logic throughout the skill, violating single-responsibility principles and complicating testing. Centralizing compatibility concerns in [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) creates a clear boundary that simplifies maintenance and enables comprehensive testing independent of any specific runtime.