How to Set Up Cross-Platform Development for i-have-adhd

Cross-platform development for i-have-adhd requires cloning the repository once and configuring runtime-specific entry points for Claude Code, Codex, Gemini CLI, Pi, OpenCode, and Zed to ensure consistent ADHD-friendly behavior across all LLM environments.

The i-have-adhd repository by ayghri provides a standardized skill set designed to optimize LLM interactions for users with ADHD. Setting up cross-platform development for i-have-adhd ensures that your custom rules and extensions work identically across all supported AI coding agents. This guide walks through the repository structure, installation procedures, and testing workflows needed to maintain compatibility while adhering to the single-source-of-truth architecture implemented in the source code.

Repository Structure and Key Files

The project uses a single source of truth architecture where skills/i-have-adhd/SKILL.md contains the canonical skill definition read by every runtime. Each agent harness reads this file directly, ensuring consistent behavior without duplication.

Key implementation files include:

• INSTALL.md – Contains the exact commands for each platform and serves as the single source of truth for installation procedures
• package.json – Declares the Pi and Oh My Pi (OMP) extension entry points via extensions/i-have-adhd.ts and the skill folder location
• extensions/i-have-adhd.ts – Runtime-agnostic TypeScript that registers the skill with Pi/OMP
• hooks/hooks.json – Declares which runtimes expose the skill automatically
• hooks/always-on.mjs – Implements the always-on hook logic for supported agents

Cloning the Repository

All runtimes read from the same source files in skills/, extensions/, and hooks/. Having a single checkout lets you develop once and test everywhere.

git clone https://github.com/ayghri/i-have-adhd.git
cd i-have-adhd

Installing Runtime-Specific Tooling

Each LLM agent runtime requires distinct installation steps to recognize the skill. The INSTALL.md file specifies the exact procedure for each platform.

Claude Code

No build step is required. Install via the marketplace:

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

Codex

Use the codex CLI to add the skill:

codex skill install ayghri/i-have-adhd

Gemini CLI

Either download the command file or install the extension as specified in INSTALL.md.

Pi and Oh My Pi (OMP)

Pi discovers the repository as a native package because package.json declares the extension location (extensions/i-have-adhd.ts) and the skill folder (skills). No additional installation is required if the repository is in your workspace.

OpenCode

Load the plugin defined in .opencode/plugins/i-have-adhd.mjs. The root opencode.json already wires the plugin, so starting the agent is sufficient:

opencode

Qwen Code

Install via the Qwen CLI:

qwen extensions install ayghri/i-have-adhd

Zed

Import the skill URL directly or copy the folder into ~/.config/zed/skills/.

Enabling Always-On Mode

For automatic application of ADHD-friendly rules without typing /i-have-adhd each session, create the flag file required by each runtime:

Claude Code:

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

OpenCode:

touch ~/.config/opencode/.i-have-adhd-always

Pi (Oh My Pi):

touch ~/.pi/agent/.i-have-adhd-always

Alternatively, set "alwaysOn": true in ~/.pi/agent/i-have-adhd.json.

The flag is read at session start and injects the full rule set automatically.

Testing Cross-Platform Compatibility

The repository ships with unit and integration tests validating each runtime's entry point. After any change, run the full suite:

python3 -m unittest discover -s tests -v

Critical test files include:

• tests/test_opencode_plugin.py – Validates plugin registration for OpenCode
• tests/test_omp_package.py – Tests the Pi extension loading mechanism
• tests/test_always_on_hooks.py – Verifies the always-on hook functionality

Passing these tests ensures that modifications to skills/i-have-adhd/SKILL.md or the extension files remain compatible across all supported platforms.

Iterating on Skill Definitions

The core behavior lives in skills/i-have-adhd/SKILL.md. Editing this file updates every runtime because each harness reads the Skill directly. After modifying the rules, restart the relevant agent or reload the plugin to propagate changes.

For example, to add a custom rule:

10. No preamble, no recaps, no closers.

Save the file, then restart your agent session to apply the update across all configured runtimes.

Summary

• Clone once: A single repository checkout supports all runtimes including Claude Code, Codex, Gemini CLI, Pi, OpenCode, Qwen Code, and Zed
• SKILL.md is canonical: Edit skills/i-have-adhd/SKILL.md to update behavior across every platform simultaneously
• Always-on flags: Create runtime-specific flag files in ~/.claude/, ~/.config/opencode/, or ~/.pi/agent/ to enable automatic skill injection
• Test thoroughly: Run python3 -m unittest discover -s tests -v to validate changes against tests/test_opencode_plugin.py, tests/test_omp_package.py, and tests/test_always_on_hooks.py
• No duplication: The architecture ensures you develop the skill logic once and deploy everywhere without platform-specific forks

Frequently Asked Questions

What file serves as the single source of truth for skill behavior?

The skills/i-have-adhd/SKILL.md file contains the canonical skill definition. Every supported runtime—including Claude Code, Pi, and OpenCode—reads this file directly to load the ADHD-friendly interaction rules, ensuring consistent behavior without maintaining separate copies for each platform.

How do I enable always-on mode specifically for Claude Code?

Create an empty flag file at ~/.claude/.i-have-adhd-always. This file triggers the always-on hook implemented in hooks/always-on.mjs, which automatically injects the skill rules at the start of every Claude Code session without requiring manual activation commands.

Which test file validates the OpenCode plugin registration?

The tests/test_opencode_plugin.py file contains unit tests that verify the plugin registration logic defined in .opencode/plugins/i-have-adhd.mjs. This test ensures that the root opencode.json correctly wires the plugin entry point and that the skill loads properly within the OpenCode runtime environment.

Can I use the same skill definition for both Pi and Zed?

Yes. Both Pi (Oh My Pi) and Zed read from the same skills/i-have-adhd/SKILL.md file. Pi discovers the skill through package.json and extensions/i-have-adhd.ts, while Zed imports the skill folder directly. Since both reference the identical skill definition, editing SKILL.md updates behavior for both runtimes simultaneously.

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