How to Set Up a Local Development Server for i-have-adhd

You can set up a local development server for i-have-adhd by cloning the repository into ~/.config/opencode/vendor/i-have-adhd, installing dependencies with Bun, registering the plugin path in your global opencode.json, and running opencode serve to launch the server on localhost:5173.

The i-have-adhd repository by ayghri is an Agent Skills package that modifies LLM outputs to follow ADHD-friendly formatting rules across supported agent runtimes like OpenCode, Claude Code, and Gemini CLI. Setting up a local development server enables real-time testing of the /i-have-adhd slash command and rapid iteration on the skill's rule set.

Prerequisites

Before setting up the local server, ensure you have the Bun JavaScript runtime installed. The repository uses Bun for dependency management and its private package ecosystem. You also need the OpenCode CLI installed globally to serve the development interface.

# Install Bun if not already present

curl -fsSL https://bun.sh/install | bash

# Install OpenCode CLI (follow official documentation for your platform)

Step 1: Clone the Repository

Clone the repository to the recommended vendor location that OpenCode expects for shared skill checkouts. According to the INSTALL.md file, placing the source under ~/.config/opencode/vendor/ ensures compatibility with the OpenCode plugin system.

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

This places the skill definition files, adapters, and the OpenCode plugin source in a predictable location for the server to reference.

Step 2: Install JavaScript Dependencies

Navigate to the cloned directory and install the Node dependencies using Bun. The package.json lists required packages including zod and the OpenCode SDK that the plugin uses to expose the skill interface.

cd ~/.config/opencode/vendor/i-have-adhd
bun install

This resolves the private Bun project dependencies required by the .opencode/plugins/i-have-adhd.mjs entry point.

Step 3: Register the Plugin with OpenCode

Configure your global opencode.json configuration file to load the i-have-adhd plugin at startup. The entry point is located at .opencode/plugins/i-have-adhd.mjs within the repository.

Create or edit ~/.config/opencode/opencode.json:

{
  "plugin": [
    "/home/$(whoami)/.config/opencode/vendor/i-have-adhd/.opencode/plugins/i-have-adhd.mjs"
  ]
}

Replace $(whoami) with your actual username or use the absolute path where you cloned the repository. This registration tells OpenCode to load the /i-have-adhd slash command and initialize the plugin hooks when the server starts.

Step 4: Start the Development Server

Launch the local OpenCode server to activate the development environment. By default, this starts a web interface accessible at http://localhost:5173.

opencode serve

The server loads the plugin specified in opencode.json, making the i-have-adhd skill available to any LLM connected through the OpenCode interface. You can now open your browser to localhost:5173 and access the chat UI to interact with the skill.

Step 5: Enable Always-On Mode (Optional)

To apply the ADHD formatting rules to every prompt without manually invoking the slash command, create the always-on flag file:

touch ~/.config/opencode/.i-have-adhd-always

When present, this file triggers the hooks/always-on.mjs hook to prepend the full ruleset from skills/i-have-adhd/SKILL.md to every system prompt automatically.

Understanding the Architecture

The i-have-adhd repository consists of three interconnected components that the development server orchestrates.

Skill Definition

The core logic resides in skills/i-have-adhd/SKILL.md, which contains the 10 concise output rules defining ADHD-friendly formatting. The server reads this file to inject the rules into LLM prompts when the skill is activated.

OpenCode Plugin

The file .opencode/plugins/i-have-adhd.mjs serves as the plugin entry point. It registers the /i-have-adhd slash command with OpenCode and implements the connection between the server runtime and the skill definition. This plugin also initializes the always-on hook system when the flag file is detected.

Always-On Hook

The hooks/always-on.mjs file monitors for the presence of ~/.config/opencode/.i-have-adhd-always. When found, it automatically prepends the skill rules to every conversation, eliminating the need to manually trigger the slash command for each chat session.

Testing and Iteration

Verify your local development server setup by opening the OpenCode UI and starting a new chat session. Type the command:

/i-have-adhd

You should see the 10-rule output style applied to the LLM's responses, confirming that the server is correctly loading the skill from ~/.config/opencode/vendor/i-have-adhd and that the plugin hook is functional.

To modify the skill behavior, edit skills/i-have-adhd/SKILL.md or the source files in .opencode/plugins/, then restart the server using Ctrl-C followed by opencode serve to reload the changes. This development workflow allows immediate verification of rule modifications.

Summary

• Clone the repository to ~/.config/opencode/vendor/i-have-adhd for standard OpenCode integration
• Install dependencies using bun install after installing the Bun runtime
• Configure the plugin path in ~/.config/opencode/opencode.json pointing to .opencode/plugins/i-have-adhd.mjs
• Start the server with opencode serve to launch localhost:5173
• Test by running /i-have-adhd in the OpenCode chat interface
• Iterate by editing SKILL.md or plugin files and restarting the server to see changes immediately

Frequently Asked Questions

What runtime does i-have-adhd require for local development?

The repository requires Bun as its JavaScript runtime. The package.json defines the project as a private Bun workspace, and the OpenCode plugin system relies on Bun's module resolution. While the skill itself is runtime-agnostic when deployed to various agents, the local development server specifically uses Bun for dependency management and execution.

Where does the always-on flag file need to be located?

The always-on flag file must be located at ~/.config/opencode/.i-have-adhd-always. The hooks/always-on.mjs plugin component specifically checks this absolute path during server initialization. When this empty flag file exists, the plugin automatically prepends the ADHD rules from skills/i-have-adhd/SKILL.md to every system prompt without requiring the /i-have-adhd slash command.

Which file contains the actual rules that the server applies?

The canonical rule set is stored in skills/i-have-adhd/SKILL.md. This file contains the 10 concise output specifications that define ADHD-friendly formatting. Both the slash command handler in .opencode/plugins/i-have-adhd.mjs and the always-on hook reference this file to inject the rules into LLM conversations.

Can I run the development server without Bun?

No. While the i-have-adhd skill is designed to work across multiple agent runtimes (Claude Code, Gemini CLI, etc.) when deployed, the local development server specifically requires Bun. The OpenCode plugin architecture and the project's package.json dependencies are built around Bun's package management and runtime features. Attempting to use Node.js or other runtimes may result in dependency resolution failures.

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