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

The 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 extension solves this problem by abstracting away runtime-specific differences.

What context-compat.ts Actually Does

Located at extensions/context-compat.ts, this module exposes three key capabilities:

The ContextMessageMarker Shape

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

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

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

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

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 — Compatibility utilities for extracting and interpreting context markers
• extensions/i-have-adhd.ts — Main runtime extension importing context-compat.ts for OMP execution
• scripts/check_context_compat.ts — Validation script testing the layer across supported runtimes

Summary

• The 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 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 creates a clear boundary that simplifies maintenance and enables comprehensive testing independent of any specific runtime.

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