How to Set Up the Development Environment for ayghri/i-have-adhd

To set up the development environment for ayghri/i-have-adhd, clone the repository, install the CLI tooling for your target runtime (Claude Code, OpenCode, Pi, etc.), and run the Python test suite to validate cross-runtime compatibility.

The ayghri/i-have-adhd repository is a multi-runtime "Agent Skill" that provides ADHD-friendly response formatting for coding assistants like Claude Code, Codex, Gemini CLI, and Zed. Setting up the development environment requires understanding its three-layer architecture and installing runtime-specific dependencies to test locally.

Prerequisites and System Requirements

Before configuring the environment, ensure you have Node.js and npm installed for TypeScript-based agents, Python 3 for running the validation suite, and the specific CLI tools for any agents you intend to test against (e.g., claude, pi, or opencode).

Repository Architecture Overview

The project follows a modular architecture separating skill logic from runtime bindings. Understanding these layers is essential for effective development.

Skill Definition Layer

The core logic resides in skills/i-have-adhd/SKILL.md. This Markdown file contains the 10 canonical output rules that define ADHD-friendly formatting. According to the source code, this file serves as the single source of truth that runtime wrappers consume either directly (Copilot, Zed) or indirectly via manifests.

Runtime Integration Layer

Each supported platform implements a lightweight wrapper that registers the /i-have-adhd command:

• hooks/hooks.json – SessionStart hook registry for Claude Code
• .claude-plugin/plugin.json – Claude Code plugin manifest
• .codex-plugin/plugin.json – Codex plugin manifest
• extensions/i-have-adhd.ts – TypeScript extension for Pi and OMP
• .opencode/plugins/i-have-adhd.mjs – OpenCode plugin entry point
• Platform-specific JSON files – gemini-extension.json, kimi.plugin.json, qwen-extension.json

Installation Manifests

The INSTALL.md file documents exact commands for each runtime, while hooks/always-on.mjs provides the session-start automation logic for persistent activation.

Step-by-Step Development Setup

Clone the Repository

Start by cloning the repository to your local machine:

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

Install Runtime-Specific Tooling

Depending on which agents you are developing for, install the corresponding CLI tools:

• Claude Code: Install via npm install -g @anthropic-ai/claude-cli (or as directed in current documentation)
• OpenCode: Install the OpenCode CLI
• Pi: Ensure the pi CLI is available
• Generic Node runtimes: Run npm install if modifying TypeScript extensions

Validate with the Test Suite

The repository includes a Python-based test suite to ensure skill compatibility across runtimes. Execute the tests from the repository root:

python3 -m unittest discover -s tests -v

This command discovers and runs all tests in the tests/ directory, validating that the skill loads correctly for each supported platform.

Installing the Skill Locally for Testing

To test modifications, you must install the skill on your target runtime.

Claude Code Installation

Install the skill via the marketplace and verify activation:

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

Invoke the skill within a session:

/i-have-adhd

To enable "always-on" mode during development, create the flag file:

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

Restart Claude Code to trigger the session-start hook defined in hooks/always-on.mjs.

OpenCode Installation

Clone the repository to the OpenCode vendor directory and register the plugin:

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

Append the plugin path to your global opencode.json:

cat <<EOF >> ~/.config/opencode/opencode.json
{ "plugin": ["/absolute/path/to/i-have-adhd/.opencode/plugins/i-have-adhd.mjs"] }
EOF

Start OpenCode and test with /i-have-adhd.

Pi and OMP Installation

For Pi, install directly from the repository URL:

pi install https://github.com/ayghri/i-have-adhd

Then start a Pi session and toggle the mode using /i-have-adhd. The TypeScript extension in extensions/i-have-adhd.ts handles the command registration for both Pi and OMP runtimes.

Development Workflow Best Practices

When modifying the skill, follow this iteration cycle:

1. Edit skills/i-have-adhd/SKILL.md for rule changes, or modify the relevant runtime wrapper in hooks/, .claude-plugin/, .opencode/plugins/, etc.
2. Reload the agent or reinstall the plugin to pick up changes (some runtimes require full restart)
3. Test by invoking /i-have-adhd and verifying output formatting
4. Validate by running python3 -m unittest discover -s tests -v to ensure cross-runtime compatibility remains intact

Because the skill contains no compiled code—only JSON manifests, TypeScript extensions, and Markdown documentation—the development environment remains lightweight, requiring only standard Node.js tooling and Python for validation.

Summary

• Clone the repository using git clone https://github.com/ayghri/i-have-adhd
• Install runtime-specific CLIs (Claude Code, OpenCode, Pi) based on your testing targets
• Test installations using commands like claude plugin install or pi install
• Validate all changes using python3 -m unittest discover -s tests -v
• Modify skills/i-have-adhd/SKILL.md for rule updates, or edit runtime-specific files in hooks/, extensions/, or .opencode/plugins/
• Enable "always-on" mode by creating ~/.claude/.i-have-adhd-always for persistent testing

Frequently Asked Questions

What file contains the actual ADHD formatting rules?

The canonical rules live in skills/i-have-adhd/SKILL.md. This file contains the 10 output formatting rules and serves as the single source of truth that all runtime wrappers reference or embed.

Do I need to compile TypeScript before testing changes?

No. While the repository includes TypeScript extensions (such as extensions/i-have-adhd.ts for Pi/OMP), the development environment treats these as lightweight scripts. Most runtimes handle TypeScript directly or require only standard npm tooling without a separate build step for this specific project.

How do I test the skill on multiple runtimes simultaneously?

Run the Python test suite with python3 -m unittest discover -s tests -v. This automated suite validates that the skill loads correctly across all supported runtimes, ensuring your changes do not break compatibility with Claude Code, Codex, OpenCode, or other agents.

Where do I find installation commands for specific agents?

Reference INSTALL.md in the repository root. This file contains detailed, runtime-specific instructions for Claude Code, Codex, Pi, OpenCode, Gemini, Kimi, Qwen, and other supported platforms.

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