# How I-Have-ADHD Reshapes AI Outputs: A Multi-Runtime Transformation Pipeline

> Discover how I-Have-ADHD transforms AI outputs with ADHD-friendly formatting. This plugin uses concise bullet points and headings to boost accessibility.

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

---

**I‑Have‑ADHD is a multi-runtime plugin that intercepts raw LLM responses and rewrites them according to ten ADHD-friendly formatting rules defined in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), making AI outputs more accessible through concise bullet points, frequent headings, and visual cues.**

The open-source repository `ayghri/i-have-adhd` provides a lightweight transformation layer that automatically reformats AI-generated content across multiple platforms. By inserting itself between the model and the user interface, this tool ensures every response—whether from Claude, OpenCode, or Codex—follows consistent accessibility guidelines without requiring manual prompting.

## The Architecture Behind Reshaping AI Outputs

The plugin operates as a middleware system that intercepts raw text before it reaches the user. According to the source code, the reshaping process relies on three architectural pillars: a canonical skill definition, runtime-specific adapters, and always-on transformation hooks.

### SKILL.md: The Canonical Rule Engine

At the heart of the transformation logic lies [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), which serves as the single source of truth for how to reshape AI outputs. This markdown file enumerates ten specific ADHD-friendly response rules, including requirements for concise bullet points instead of dense paragraphs, frequent headings to segment information, and visual cues for rapid scanning.

When the plugin activates, it loads these rules into memory to guide the rewriting process across all supported platforms.

### Runtime Adapters for Cross-Platform Compatibility

The repository ships dedicated adapters for every supported AI runtime, ensuring the reshaping logic works consistently across different platforms:

- **OpenCode**: Configured via [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json) with the plugin entry point at `.opencode/plugins/i-have-adhd.mjs`
- **Claude**: Uses [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) alongside [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) for Anthropic's ecosystem
- **Codex**: Implemented through [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) for OpenAI's coding assistant
- **Pi / OMP**: Leverages [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) entries ("pi" and "omp") with TypeScript extensions in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)

Each adapter registers a hook that intercepts the model's raw output before display, routing it through the shared transformation engine to reshape AI outputs uniformly.

## The Transformation Pipeline

The actual reshaping occurs through a coordinated sequence of file executions and algorithmic processing.

### Always-On Hooks

The `hooks/always-on.mjs` script executes automatically when the host platform initializes. This script registers persistent listeners that receive every raw LLM response, guaranteeing that chat messages, completions, and tool outputs all undergo the ADHD-friendly rewrite.

```javascript
// Conceptual implementation from hooks/always-on.mjs
export async function onResponse(raw: string): Promise<string> {
  // Apply the ADHD-friendly rules
  return rewrite(raw);
}

```

This mechanism ensures that every AI output is reshaped automatically without requiring users to invoke special commands for each interaction.

### The Core Rewrite Algorithm

The transformation engine resides in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts). This TypeScript implementation parses raw output into logical sections, applies the ten rules from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), and reassembles the text while preserving semantic meaning.

The algorithm follows this pipeline:
1. **Parse**: Deconstruct the raw LLM output into logical content blocks
2. **Transform**: Apply ADHD-friendly rules (insert emojis, add whitespace, create numbered steps)
3. **Validate**: Ensure the rewritten content maintains the original informational value
4. **Return**: Emit the formatted text to the user's interface

```typescript
// Example usage pattern from extensions/i-have-adhd.ts
import { rewrite } from '../extensions/i-have-adhd.js';

export async function onResponse(raw: string): Promise<string> {
  // Transform dense text into scannable format
  return rewrite(raw);
}

```

## Validation and Quality Assurance

To ensure the reshaping logic maintains accuracy while improving readability, the repository includes automated evaluation tools.

### Automated Evaluation Harness

The [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) script executes the skill against curated test prompts, comparing outputs against the rubric defined in [`evals/rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md). This ensures that bullet points remain factually complete and visual cues don't obscure critical information.

```bash

# Validate rewrite quality on specific test cases

python -m scripts.run_evals \
  --case "Explain the steps to bake a cake" \
  --model gpt-4o

```

### Unit Testing

Platform-specific tests like [`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py) verify that adapters correctly register hooks and that the transformation chain executes without errors across different runtime environments.

## How to Use I-Have-ADHD to Reshape AI Outputs

Users activate the plugin through platform-specific commands or automatic hooks.

### Command Line Invocation

For OpenCode users, the plugin exposes a direct CLI interface:

```bash

# Process a prompt with automatic ADHD-friendly formatting

opencode i-have-adhd "Explain quantum entanglement in plain language"

```

### Automatic Integration

Once installed, the always-on hooks ensure that every interaction with supported models (Claude, Gemini, Qwen, Kimi, etc.) automatically receives the optimized formatting without additional user intervention.

## Summary

I-Have-ADHD reshapes AI outputs by inserting a transparent middleware layer that enforces accessibility-focused formatting guidelines. Key technical aspects include:

- **Canonical Rules**: [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) defines ten specific formatting requirements that guide all transformations
- **Universal Coverage**: Runtime adapters for OpenCode, Claude, Codex, Pi, OMP, Gemini, Qwen, and Kimi ensure consistent behavior across platforms
- **Automatic Interception**: `hooks/always-on.mjs` registers persistent listeners that process every LLM response without manual triggering
- **TypeScript Engine**: [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) implements the parsing, transformation, and reassembly logic
- **Validated Output**: [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) and the test suite ensure rewritten content maintains accuracy while improving scannability

## Frequently Asked Questions

### How does I-Have-ADHD modify AI responses without changing their meaning?

The plugin uses a rule-based transformation engine in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) that parses content into logical sections and applies structural changes—such as converting paragraphs to bullet points or adding headers—while preserving all factual information. The [`evals/rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md) file defines strict validation criteria to ensure semantic accuracy post-transformation.

### Which AI platforms support the I-Have-ADHD output reshaping?

The repository provides native adapters for eight major runtimes: OpenCode, Claude, Codex, Pi, OMP, Gemini, Qwen, and Kimi. Each platform uses dedicated configuration files (such as [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json) or [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json)) to register the transformation hooks locally.

### Can I customize the ADHD-friendly rules used to reshape outputs?

While the canonical rules live in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), advanced users can fork the repository and modify this markdown file to adjust formatting preferences. The [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) engine dynamically loads these rules at runtime, allowing customization of bullet styles, header frequencies, and visual cue placement.

### Does the plugin impact AI response latency?

The transformation adds minimal overhead—typically milliseconds—since `hooks/always-on.mjs` operates locally on text strings after the LLM has completed generation. The rewrite algorithm in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) uses efficient string parsing and doesn't require additional API calls, keeping latency impact negligible for most use cases.