# How the i-have-adhd Plugin Integrates with the Claude Code Plugin System

> Discover how the i-have-adhd plugin seamlessly integrates with Claude Code. Learn about plugin manifests, marketplace metadata, and session-start hooks for ADHD-friendly responses.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-19

---

**The i-have-adhd plugin integrates with the Claude Code plugin system through a plugin manifest, marketplace metadata, and a session-start hook that conditionally injects ADHD-friendly response rules into the system prompt when a user opts in.**

The `ayghri/i-have-adhd` repository implements a Claude Code skill that reformats assistant output to be ADHD-friendly. Rather than requiring manual configuration on every launch, the integration leverages native Claude Code extension points so the runtime can discover, list, and automatically apply the ruleset. This article breaks down the exact file layout and hook mechanism that make the integration possible.

## Plugin Manifest and Marketplace Registration

Every Claude Code plugin begins with a declaration. In [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json), the plugin registers its name, version, and basic identity so the Claude Code runtime recognizes it as a valid extension.

The marketplace listing is controlled by [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json), which supplies schema-validated metadata such as description and category. This file is what allows Claude Code to display the plugin in its marketplace UI and categorize it appropriately as a productivity tool.

## Session-Start Hook Architecture

The automatic behavior is driven by Claude Code's hook system, which lets external scripts run at specific lifecycle points. The file [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) registers a `SessionStart` event that tells Claude Code to execute a Node command whenever a new session begins.

### Hook Registration

Inside [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json), the `SessionStart` entry triggers the command `node -e ".../always-on.mjs"`. Because the hook is bound to session lifecycle events, it fires not only on fresh starts but also on resume, clear, and compact operations. This guarantees the ruleset is present even when the context is reset.

### Always-On Logic

When executed, `hooks/always-on.mjs` checks for the opt-in flag file at `~/.claude/.i-have-adhd-always`. If the flag exists, the script reads [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), strips its YAML front-matter, and writes the cleaned ruleset to stdout prefixed with the notice `ADHD MODE ACTIVE (always-on)...`.

Claude Code captures this stdout and feeds it directly into the system prompt. The injected output looks similar to:

```text
ADHD MODE ACTIVE (always-on). The ruleset below applies to every response. 
"stop adhd mode" turns it off for this session; delete /home/you/.claude/.i-have-adhd-always to turn always-on off for good.

1. Lead with the next actionable step.
2. Number each step.
3. Suppress tangential information.

```

Consequently, every subsequent response obeys the rules defined in the skill file. The script is intentionally **non-blocking**; any error results in an immediate `process.exit(0)`, ensuring that session startup is never interrupted by a plugin failure.

## User Activation and Usage

Users control the plugin through two complementary interfaces. A slash command triggers temporary activation, while a filesystem flag enables persistent, automatic injection across every new session.

```text

# Enable ADHD mode for the current session

/i-have-adhd

# Enable always-on (global) mode

mkdir -p ~/.claude
touch ~/.claude/.i-have-adhd-always

# Disable ADHD mode for the current session

stop adhd mode

# Turn off the global always-on flag

rm ~/.claude/.i-have-adhd-always

```

### Per-Session Command

Typing `/i-have-adhd` inside Claude Code enables ADHD mode for the current session only. This command invokes the skill without creating any persistent flag, making it ideal for one-off tasks.

### Global Always-On Flag

To make the behavior persist across restarts, create the opt-in flag file with `touch ~/.claude/.i-have-adhd-always`. Once this file exists, the `SessionStart` hook automatically loads and injects the ruleset on every new session.

You can disable the global behavior by deleting the flag with `rm ~/.claude/.i-have-adhd-always`. You can also override the active session by typing `stop adhd mode` or `normal mode`, which disables the rules for that specific conversation without removing the global flag.

## Key Files

- [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) — Declares the plugin to Claude Code. [Source](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json)
- [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) — Provides marketplace metadata. [Source](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json)
- [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) — Registers the `SessionStart` hook. [Source](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json)
- `hooks/always-on.mjs` — Implements the always-on flag detection and ruleset injection. [Source](https://github.com/ayghri/i-have-adhd/blob/main/hooks/always-on.mjs)
- [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) — Contains the full ADHD-friendly ruleset injected into the prompt. [Source](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)

## Summary

- The plugin declares itself to Claude Code via [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) and [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json).
- Automatic injection relies on [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) registering a `SessionStart` command that runs `hooks/always-on.mjs`.
- The always-on script checks for `~/.claude/.i-have-adhd-always`, then reads [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and outputs the cleaned ruleset to stdout for prompt injection.
- Users can activate ADHD mode per-session with `/i-have-adhd` or globally with a filesystem flag.
- The hook exits cleanly on error (`process.exit(0)`) so it never blocks session startup.

## Frequently Asked Questions

### How does the i-have-adhd plugin register itself with Claude Code?

The plugin uses [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) to declare its identity and [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) to supply listing metadata. These files sit in a known directory that Claude Code scans when discovering available skills.

### What file controls the automatic start-up behavior?

The [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) file maps the `SessionStart` event to the command that executes `hooks/always-on.mjs`. This is the entry point for all automatic, always-on functionality.

### How do I turn off ADHD mode once it is enabled?

For the current session, type `stop adhd mode` or `normal mode`. To disable the global always-on setting, remove the flag file by running `rm ~/.claude/.i-have-adhd-always`.

### Is the session-start hook safe if the plugin files are corrupted?

Yes. The `hooks/always-on.mjs` script is designed to be non-blocking. It traps errors and exits immediately with `process.exit(0)`, so Claude Code will start normally even if the skill files are missing or unreadable.