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

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, and applying ADHD-friendly response transformations defined in 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

The file .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.

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

UI Integration via marketplace.json

The .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.

{
  "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

The runtime reads 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.

{
  "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 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

The file 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 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:

{
  "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:

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 file registers the plugin identity with the Claude Code runtime.
• marketplace.json supplies UI metadata and default prompts for the Claude Code interface.
• 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 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 and 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 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 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 as the primary specification for the base plugin behavior.

What is the difference between plugin.json and marketplace.json?

The plugin.json file contains technical registration data required by the Claude Code runtime architecture, including the plugin name and version. The marketplace.json file provides user-facing metadata such as display names, icons, and default prompts used by the Claude Code UI and marketplace listings.

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