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

Fork the repository, install Node.js ≥18, modify the TypeScript extension in 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:

   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:

   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: 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: 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: 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 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:

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 or 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:

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) 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 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, copy the changes to the Cursor directory as specified in CONTRIBUTING.md:

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 to add commands using pi.registerCommand, and update package.json if the manifest changes.
• Synchronize 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.

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