# How to Build the i-have-adhd Project from Source: A Complete Guide > Learn to build the i-have-adhd project from source. Follow our guide to clone the repo, install dependencies, compile extensions, and run tests for a successful setup. - Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd) - Tags: how-to-guide - Published: 2026-08-30 --- **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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) declares the extension entry points, allowing Pi and OMP runtimes to discover the extension automatically. - **Installation Documentation** – [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) and [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/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: ```bash 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: ```bash # 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: ```bash # 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`](https://github.com/ayghri/i-have-adhd/blob/main/tsconfig.json) exists in the repository, compile the extension directly: ```bash 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: ```bash 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: ```bash 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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) automatically points Pi and OMP runtimes to [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts). After running `npm install`, install the package into your runtime: ```bash # 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`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json). Alternatively, configure the plugin manually: ```bash # Add to your global OpenCode config cat < ~/.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: ```bash # 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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.