How to Build the i-have-adhd Project from Source: A Complete Guide

Building the i-have-adhd project from source requires cloning the repository, installing Node.js dependencies with npm or bun, optionally compiling the TypeScript extension, and running Python-based unit tests to validate the installation.

The i-have-adhd repository by ayghri is a lightweight, multi-runtime Agent-Skill designed to inject ADHD-friendly response rules into AI conversations. Unlike traditional software projects that require complex compilation pipelines, this project consists primarily of a Markdown rule-set and a small TypeScript extension, making the build process straightforward but specific to each supported runtime.

Understanding the Project Architecture

Before building, it is essential to understand how the components interact across different AI runtimes.

Core Components

The repository follows a minimal architecture with five key components:

• Skill Definition – The skills/i-have-adhd/SKILL.md file contains the plain-text Markdown rules that define the 10 ADHD-friendly response patterns. Every supported runtime reads this file to modify model behavior.
• TypeScript Extension – Located at extensions/i-have-adhd.ts, this module loads the skill, tracks the "ADHD mode" state, and implements runtime-specific hooks such as session_start and input for Pi and OMP.
• OpenCode Plugin – The .opencode/plugins/i-have-adhd.mjs file provides an ES module that registers the /i-have-adhd command and context-sync logic for the OpenCode server.
• Package Metadata – package.json declares the extension entry points, allowing Pi and OMP runtimes to discover the extension automatically.
• Installation Documentation – INSTALL.md and README.md provide platform-specific consumption instructions.

Prerequisites for Building

To successfully build the i-have-adhd project from source, your environment must meet the following requirements:

• Node.js version 14 or higher
• npm or bun package manager (bun is bundled in the repository)
• Python 3 for running the unit test suite and evaluation scripts
• Git for cloning the repository

Step-by-Step Build Instructions

Follow these steps to build the project from source code:

Clone the Repository

Start by cloning the GitHub repository and navigating into the project directory:

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

Install Dependencies

Install the Node.js dependencies using your preferred package manager. The project uses zod as the only external library for OpenCode metadata validation:

# Using npm

npm install

# Or using bun (recommended, comes bundled)

bun install

This command resolves all development dependencies required for the TypeScript source files.

Compile the TypeScript Extension

While the runtime loaders accept raw .ts files, compiling ahead of time enables linting and bundling:

# Using the built-in tsconfig (if present)

npx tsc -p .

# Or using bun's built-in TypeScript compiler

bun run build

If no tsconfig.json exists in the repository, compile the extension directly:

npx tsc extensions/i-have-adhd.ts --outDir dist

Run the Test Suite

The repository includes Python-based unit tests for the OpenCode plugin and runtime validation. Execute the test suite to verify the build:

python3 -m unittest discover -s tests -v

All tests should pass. Failures typically indicate missing Node dependencies or outdated runtime versions.

Validate the Evaluation Harness

Optionally, verify that the skill integrates cleanly with the evaluation framework:

python3 scripts/run_evals.py validate

Deployment for Different Runtimes

After building the i-have-adhd project from source, deploy the artifacts to your preferred runtime:

Pi and OMP Installation

The package.json automatically points Pi and OMP runtimes to extensions/i-have-adhd.ts. After running npm install, install the package into your runtime:

# Install the extension (run once)

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

# Toggle ADHD mode during a session

/i-have-adhd           # toggles on/off

/i-have-adhd on        # explicitly enable

/i-have-adhd off       # explicitly disable

OpenCode Plugin Setup

Copy the .opencode directory to your OpenCode vendor location, or run OpenCode directly from the checkout. The plugin is already referenced in opencode.json.

Alternatively, configure the plugin manually:

# Add to your global OpenCode config

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

# Start OpenCode and enable the skill

opencode
/i-have-adhd

Claude Code Integration

For Claude Code, create a flag file to enable the always-on hook:

# Enable automatic rule injection

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

# To disable for a single session, type:

stop adhd mode

Summary

• Clone the repository from https://github.com/ayghri/i-have-adhd.git
• Install Node.js dependencies using npm install or bun install
• Compile the TypeScript extension with npx tsc -p . or bun run build (optional but recommended)
• Test the build using python3 -m unittest discover -s tests -v
• Deploy to Pi/OMP via package.json entry points, to OpenCode via the .opencode/plugins/i-have-adhd.mjs module, or to Claude Code via the flag file mechanism
• Reference the SKILL.md file at skills/i-have-adhd/SKILL.md for the definitive rule set that drives the behavior

Frequently Asked Questions

What is the minimum Node.js version required to build i-have-adhd?

Node.js version 14 or higher is required to build the i-have-adhd project from source. The TypeScript extension and OpenCode plugin rely on modern JavaScript features that are fully supported in Node 14+.

Can I run the TypeScript extension without compiling it to JavaScript?

Yes, the runtime loaders for Pi and OMP accept raw .ts files directly. However, compiling the TypeScript ahead of time using npx tsc or bun run build is recommended for linting, type checking, and bundling purposes.

Why does a TypeScript project use Python for testing?

The Python test suite in the tests/ directory validates the OpenCode plugin integration and runtime behavior using python3 -m unittest. This approach ensures the skill integrates correctly with the evaluation harness and external runtime environments.

Where is the actual ADHD behavior logic defined?

The core behavior is defined in skills/i-have-adhd/SKILL.md, a plain-text Markdown file containing the 10 ADHD-friendly response rules. The TypeScript extension (extensions/i-have-adhd.ts) and OpenCode plugin (.opencode/plugins/i-have-adhd.mjs) serve as loaders that inject these rules into the model's context window.

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