# How the Claude Code Runtime Architecture Implements the i-have-adhd Plugin

> Discover how Claude Code runtime architecture integrates the i-have-adhd plugin. Learn about manifest scanning, hook registration, and ADHD-friendly response transformations for enhanced usability.

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

---

**The Claude Code runtime implements the i-have-adhd plugin by scanning the `.claude-plugin` directory for manifest files, registering the always-on hook via [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json), and applying ADHD-friendly response transformations defined in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) to every Claude request.**

The `ayghri/i-have-adhd` repository extends Claude Code with specialized response formatting optimized for ADHD users. The Claude Code runtime architecture integrates this plugin through a declarative manifest system and a persistent hook-based processing pipeline that automatically reshapes every response without requiring manual invocation.

## Plugin Discovery in the Claude Code Runtime Architecture

The runtime begins implementation by locating the hidden `.claude-plugin` directory at the repository root. This directory contains standardized JSON files that declare the plugin's identity and capabilities for automatic discovery.

### Core Identity via [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json)

The file [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) serves as the primary manifest, registering the plugin with the Claude Code runtime through standardized metadata fields including name, version, and description.

```json
{
  "name": "i-have-adhd",
  "version": "1.0.0",
  "description": "ADHD-friendly response formatting for Claude"
}

```

### UI Integration via [`marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/marketplace.json)

The [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) file extends the manifest with user interface metadata required by the Claude Code UI, including display names, icons, default prompts, and declared capabilities.

```json
{
  "display_name": "I Have ADHD",
  "description": "Reframes Claude responses for ADHD accessibility",
  "icon": "brain-lightning",
  "default_prompts": ["Make this ADHD-friendly", "Action-first formatting"],
  "capabilities": ["response_transformation"]
}

```

## Hook Registration in the Claude Code Runtime

After manifest validation, the Claude Code runtime architecture loads the plugin's processing logic through the hooks system defined in the `hooks/` directory.

### Hook Declaration in [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json)

The runtime reads [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) to identify which lifecycle events the plugin intercepts. For i-have-adhd, this registers the always-on hook that processes every Claude request through the pipeline.

```json
{
  "hooks": [
    {
      "name": "always-on",
      "entry": "always-on.mjs",
      "type": "transform"
    }
  ]
}

```

### Request Processing in `always-on.mjs`

The file `hooks/always-on.mjs` implements the transformer that the runtime calls during the response generation phase. This module injects the ADHD-friendly response transformer into Claude Code's processing pipeline, ensuring every output passes through the accessibility filter.

According to the source code in `ayghri/i-have-adhd`, this hook applies the transformation rules from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) to restructure content into action-first formats with numbered steps, removing tangents and adding visible progress indicators.

## Skill Implementation in the Claude Code Runtime

The runtime applies specific formatting rules defined in the skills directory to ensure consistent output restructuring across all Claude interactions.

### Canonical Rules in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)

The file [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) contains the definitive transformation specifications that the always-on hook references. These rules mandate:

- Action-first response structures
- Numbered execution steps
- Elimination of tangential information
- State restatement and visible progress tracking

The Claude Code runtime passes these skill definitions to the transformation hook during initialization, ensuring every response adheres to the accessibility guidelines without requiring users to manually prompt for formatting.

### Runtime Entry Points

The [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) file documents how the Claude Code runtime initializes the plugin system, serving as the architectural entry point reference for developers integrating similar accessibility plugins.

## Code Examples

Developers can interact with the i-have-adhd plugin through standardized Claude Code prompts or programmatically via the OpenCode SDK.

### Using Default Prompts

Invoke the plugin using the default prompts defined in [`marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/marketplace.json):

```json
{
  "model": "claude-3",
  "prompt": [
    "Use i-have-adhd for this task.",
    "Make this answer action-first and easy to execute.",
    "Review this response for ADHD-friendly structure."
  ],
  "input": "Explain how to set up a local development environment for a Node.js project."
}

```

### Programmatic Hook Invocation

Access the always-on transformer directly through the runtime SDK:

```javascript
import { runPlugin } from '@opencode-ai/sdk';

const rawResponse = await runPlugin('i-have-adhd', {
  model: 'claude-3',
  userPrompt: 'Summarise the key points of the latest React release.'
});

console.log(rawResponse); // Output is already reshaped by the ADHD transformer

```

## Summary

- The **[`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json)** file registers the plugin identity with the Claude Code runtime.
- **[`marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/marketplace.json)** supplies UI metadata and default prompts for the Claude Code interface.
- **[`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json)** declares the always-on hook that intercepts all requests in the pipeline.
- **`hooks/always-on.mjs`** implements the transformer that applies ADHD-friendly formatting to every response.
- **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** contains the canonical formatting rules referenced by the transformation logic.
- The runtime automatically discovers and loads these components when scanning the repository root, enabling zero-configuration plugin activation.

## Frequently Asked Questions

### Where does Claude Code look for plugin manifests?

Claude Code scans the repository root for a hidden `.claude-plugin` directory containing [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) and [`marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/marketplace.json). This standardized location allows the runtime architecture to automatically discover and register plugins without additional configuration paths or manual installation steps.

### How does the always-on hook modify Claude responses?

The always-on hook defined in `hooks/always-on.mjs` intercepts every response after generation but before display. It applies the transformation rules from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) to restructure content into action-first formats with numbered steps, removing tangents and adding progress indicators that accommodate ADHD cognitive patterns.

### Can developers override the default ADHD formatting rules?

While the [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file provides canonical rules, developers can extend the transformation logic in `always-on.mjs` or provide custom skill configurations. However, the runtime always references [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) as the primary specification for the base plugin behavior.

### What is the difference between [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) and [`marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/marketplace.json)?

The [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) file contains technical registration data required by the Claude Code runtime architecture, including the plugin name and version. The [`marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/marketplace.json) file provides user-facing metadata such as display names, icons, and default prompts used by the Claude Code UI and marketplace listings.