# How to Contribute to the i-have-adhd VS Code Plugin: A Complete Developer Guide

> Learn how to contribute to the i-have-adhd VS Code plugin. Fork the repo, modify code, run tests, and submit your PR to enhance this ADHD productivity tool.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-24

---

**Fork the repository, install Node.js ≥18, modify the TypeScript extension in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), run Python unit tests, and submit a PR with proper labels to contribute to the i-have-adhd VS Code plugin.**

The i-have-adhd plugin is a lightweight extension for the Pi coding-agent framework that enhances AI-assisted development in VS Code. Contributing to this open-source project involves working with TypeScript extension code, synchronizing skill definitions, and validating changes across multiple runtimes. This guide walks through the exact steps required to set up your environment, implement features, and submit changes to the `ayghri/i-have-adhd` repository.

## Setting Up Your Development Environment

Before modifying the **i-have-adhd VS Code plugin**, you must configure a local development environment compatible with the Pi runtime.

1.  **Fork and clone** the repository:

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

2.  **Install Node.js ≥18**. The project uses native ESM (ECMAScript Modules), requiring Node.js version 18 or higher.

3.  **Install dependencies**. The runtime footprint is minimal, with only the Pi API as a direct dependency:

    ```bash
    npm install
    ```

## Understanding the Codebase Structure

The repository organizes VS Code-specific logic across three critical locations. Understanding these file paths ensures you modify the correct components when contributing to **i-have-adhd development**.

-   **[`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)**: The main VS Code extension entry point. This file registers the `/i-have-adhd` toggle command, manages the enabled/disabled state, and injects the rule-set into active conversations.

-   **[`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json)**: Contains the plugin manifest under the `pi.extensions` field. VS Code discovers the extension through this configuration when the Pi extension is installed.

-   **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)**: Stores the canonical skill rules that the extension injects into the AI context. Any modification to these instructions affects how the AI assistant behaves when ADHD-friendly mode is active.

## Implementing New Features

To extend functionality, edit [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) and leverage the `pi.registerCommand` method exposed by the Pi runtime.

### Example: Adding a Status Command

Suppose you want to expose a `/i-have-adhd status` command that displays the current state without toggling it. Add the following TypeScript code to [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts):

```typescript
pi.registerCommand("i-have-adhd-status", {
  description: "Show whether ADHD-friendly mode is currently enabled",
  handler: async (_args, ctx) => {
    const state = enabled ? "ON" : "OFF";
    ctx.ui.notify(`ADHD mode is currently ${state}`, "info");
  },
});

```

This snippet registers a new command with the **Pi API**, using the `handler` callback to access the UI context (`ctx.ui`) and display a notification. Update [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md) or [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) if your change affects the user-facing command API.

## Testing Your Changes

The repository maintains cross-runtime compatibility through a Python-based unit test suite.

Run the tests with:

```bash
python3 -m unittest discover -s tests -v

```

If you add new logic, create corresponding test cases in `tests/` (for example, [`test_i_have_adhd_extension.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_i_have_adhd_extension.py)) to verify behavior across different host runtimes.

### Validating in VS Code

1.  Open the repository folder in VS Code.
2.  Launch a new Pi session via the command palette: `Ctrl+Shift+P` → **"Pi: Start Session"**.
3.  Invoke your commands using `Ctrl+Shift+P` → **"Pi: Run Command"**.
4.  Verify that enabling the plugin injects the rules from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) into the chat context, and that any new commands (like `status`) display the correct notifications.

## Synchronizing Skill Files

Because the project supports both VS Code (via Pi) and Cursor editors, you must keep the skill definitions synchronized. When you modify [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), copy the changes to the Cursor directory as specified in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md):

```bash
cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md
cmp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md

```

The `cmp` command verifies byte-for-byte equality between the source and the copy, preventing drift between editor implementations.

## Submitting Your Contribution

After validating your changes locally, submit a pull request following the repository's labeling conventions.

Apply these labels to your PR:
-   **Target:Integrations**: For VS Code or Pi framework changes.
-   **Author:AI** or **Author:Human**: Indicates whether the primary contribution was authored by an AI assistant or a human developer.
-   **Workflow:enhancement**: For new features, or `Workflow:bugfix` for corrections.

Fill out the PR description template with specific details: what changed, why the change was necessary, before/after behavior, verification steps, and any side effects on the VS Code integration.

## Summary

-   **Install Node.js ≥18** and run `npm install` to prepare the development environment for the i-have-adhd plugin.
-   **Modify [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)** to add commands using `pi.registerCommand`, and update **[`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json)** if the manifest changes.
-   **Synchronize [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)** to the `.cursor/` directory after editing rule definitions.
-   **Run Python unit tests** with `python3 -m unittest discover -s tests -v` to ensure cross-runtime compatibility.
-   **Label your PR** with `Target:Integrations` and the appropriate author/workflow tags to streamline code review.

## Frequently Asked Questions

### What Node.js version is required for i-have-adhd development?

The project requires **Node.js ≥18** because it uses native ESM (ECMAScript Modules). Earlier versions lack full support for the module system used by the Pi coding-agent framework.

### How do I test my changes locally in VS Code?

Open the repository in VS Code, ensure the Pi extension is installed, then launch **"Pi: Start Session"** from the command palette. Invoke your commands via **"Pi: Run Command"** to verify that the extension registers correctly and injects the skill rules into the conversation context.

### Why do I need to sync the SKILL.md file to the .cursor directory?

The repository supports both VS Code (via the Pi extension) and the Cursor editor. The `.cursor/skills/` directory contains a copy of the rule definitions used by Cursor's AI implementation. Synchronizing ensures consistent behavior across both editors, preventing the VS Code and Cursor versions from diverging.

### What labels should I use when creating a pull request?

Use **Target:Integrations** for VS Code-related changes, **Author:AI** or **Author:Human** to identify the contributor type, and **Workflow:enhancement** (or `bugfix`) to classify the change type. These labels automate triage and ensure maintainers route your contribution to the correct review queue.