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

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, 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, 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 registers a SessionStart event that tells Claude Code to execute a Node command whenever a new session begins.

Hook Registration

Inside 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, 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:

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.

# 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 — Declares the plugin to Claude Code. Source
• .claude-plugin/marketplace.json — Provides marketplace metadata. Source
• hooks/hooks.json — Registers the SessionStart hook. Source
• hooks/always-on.mjs — Implements the always-on flag detection and ruleset injection. Source
• skills/i-have-adhd/SKILL.md — Contains the full ADHD-friendly ruleset injected into the prompt. Source

Summary

• The plugin declares itself to Claude Code via .claude-plugin/plugin.json and .claude-plugin/marketplace.json.
• Automatic injection relies on 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 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 to declare its identity and .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 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.

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