How to Troubleshoot Common Issues with the i-have-adhd Plugin

Most i-have-adhd plugin failures stem from missing always-on flag files, incorrectly registered skill paths, or conflicting plugin hooks that overwrite the system prompt injector.

The i-have-adhd plugin by ayghri reshapes LLM output to suit readers with ADHD by injecting rules from skills/i-have-adhd/SKILL.md into the model’s system prompt. Learning how to troubleshoot common issues with the i-have-adhd plugin ensures consistent activation across Claude Code, OpenCode, and other supported runtimes.

Understanding the Plugin Architecture

The plugin operates in two activation modes: on-demand (triggered by typing /i-have-adhd) and always-on (controlled via flag files). For Claude Code, the always-on flag resides at ~/.claude/.i-have-adhd-always; for OpenCode, it is located at ~/.config/opencode/.i-have-adhd-always. When active, the implementation in .opencode/plugins/i-have-adhd.mjs prepends the rule-set to every system prompt using the experimental.chat.system.transform hook.

Symptom: The Skill Does Not Activate

If you do not see the "ADHD MODE ACTIVE" banner, the runtime failed to locate the skill directory or the flag file is missing.

Verify the Always-On Flag File

For Claude Code, confirm the presence of the trigger file:

ls ~/.claude/.i-have-adhd-always && echo "Flag present"

For OpenCode, check the equivalent path:

ls ~/.config/opencode/.i-have-adhd-always && echo "Flag present"

If these files do not exist, create them using touch to enable always-on mode, or remove them with rm to disable it.

Check the Skill Path Registration

The runtime must include the skill directory in its skills.paths list. In .opencode/plugins/i-have-adhd.mjs, the config hook registers this path automatically during installation. If manual intervention is required, ensure the repository is cloned to the correct vendor directory:

rm -rf ~/.config/opencode/vendor/i-have-adhd
git clone https://github.com/ayghri/i-have-adhd ~/.config/opencode/vendor/i-have-adhd

Symptom: Responses Are Not Reshaped

When the plugin activates but outputs remain unchanged, the YAML front-matter in SKILL.md may not be stripping correctly, or the injection logic is failing silently.

Inspect the Ruleset Injection Logic

In .opencode/plugins/i-have-adhd.mjs, the rulesetBody() function uses a regex (lines 38-42) to remove YAML front-matter from skills/i-have-adhd/SKILL.md before injection. If this regex fails due to file corruption or altered delimiters, the rules inject incorrectly or not at all. Verify that SKILL.md begins and ends its front-matter block with --- markers.

Check for Silent Runtime Errors

The plugin wraps critical injection logic in try { … } catch (e) {} blocks. Exceptions here abort the injection without displaying an error banner. Check your runtime logs for stack traces referencing the i-have-adhd plugin to identify parsing failures.

Symptom: Conflicting Plugins Overwrite Rules

Another plugin’s experimental.chat.system.transform hook may execute after the i-have-adhd hook, overwriting output.system and discarding the ADHD rules.

Resolve Hook Ordering Conflicts

The i-have-adhd plugin appends its rules to the last element of the system array (lines 68-72 of the OpenCode plugin). If another plugin overwrites the entire output.system array rather than appending to it, the rules disappear. Ensure the i-have-adhd plugin runs last in your configuration chain, or modify conflicting plugins to preserve existing system prompt content.

Step-by-Step Debugging Workflow

Follow this systematic approach to troubleshoot common issues with the i-have-adhd plugin:

1. Confirm installation using your runtime’s specific command (e.g., claude plugin install i-have-adhd@i-have-adhd for Claude Code or agy plugin install https://github.com/ayghri/i-have-adhd for Agy).

2. Validate the flag file exists at the platform-specific path to ensure always-on mode is recognized.

3. Inspect the injected prompt by checking if the header appears in the system context. If missing, the experimental.chat.system.transform hook did not execute. You can manually test the injection with:

   node -e "import plugin from './.opencode/plugins/i-have-adhd.mjs'; \
       (await plugin())?.['experimental.chat.system.transform'](null,{system:['']});"

4. Test on-demand activation using the /i-have-adhd command to bypass flag-file issues and verify the skill loads.

5. Reinstall the skill to reset paths and clear corruption:

   claude plugin uninstall i-have-adhd
   claude plugin marketplace add ayghri/i-have-adhd
   claude plugin install i-have-adhd@i-have-adhd

Summary

• Always-on activation requires flag files at ~/.claude/.i-have-adhd-always (Claude Code) or ~/.config/opencode/.i-have-adhd-always (OpenCode).
• Skill registration depends on the config hook in .opencode/plugins/i-have-adhd.mjs properly adding the skill path to the runtime’s search list.
• Front-matter stripping relies on the rulesetBody() regex in lines 38-42 of the OpenCode plugin to parse skills/i-have-adhd/SKILL.md correctly.
• Hook conflicts occur when other plugins overwrite output.system after the i-have-adhd transform hook appends its rules.

Frequently Asked Questions

Why does the i-have-adhd plugin not show the "ADHD MODE ACTIVE" banner?

The banner appears only when the always-on flag file exists or when you manually trigger the skill via command. Verify the file exists at ~/.claude/.i-have-adhd-always for Claude Code or ~/.config/opencode/.i-have-adhd-always for OpenCode. If the flag is present but the banner still does not appear, the skill path is likely missing from the runtime’s skills.paths configuration.

How do I fix responses that are not being reformatted for ADHD readability?

This indicates the rules from skills/i-have-adhd/SKILL.md are not being injected into the system prompt. Check that the file contains valid YAML front-matter delimited by --- markers. In .opencode/plugins/i-have-adhd.mjs, the rulesetBody() function processes this file using a regex on lines 38-42; ensure this execution completes without runtime exceptions by verifying file permissions and syntax.

Can other plugins interfere with i-have-adhd functionality?

Yes. If another plugin implements experimental.chat.system.transform and overwrites output.system instead of appending to it, the ADHD rules will be removed. The i-have-adhd plugin specifically appends to the last element of the system array (lines 68-72), so ensure it runs after other plugins or modify conflicting plugins to preserve the existing system prompt content.

How do I completely reset the plugin configuration?

Delete the vendor directory and flag files, then reinstall using your runtime’s commands:

rm -rf ~/.config/opencode/vendor/i-have-adhd
rm ~/.config/opencode/.i-have-adhd-always

# Reinstall using your specific runtime installer

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