Configuration Options for the i-have-adhd Skill in Pi: A Complete Guide

The i-have-adhd skill in Pi can be configured via a JSON configuration file (i-have-adhd.json) with alwaysOn and hideStatus boolean options, or through the --adhd command-line flag that overrides defaults for single sessions.

The i-have-adhd skill enhances Pi with ADHD-friendly conversation rules by injecting specialized guidelines from skills/i-have-adhd/SKILL.md. This guide documents every i-have-adhd skill configuration option available in the ayghri/i-have-adhd repository, covering persistent JSON settings, runtime CLI flags, and interactive commands.

JSON Configuration File Options

Pi loads the i-have-adhd skill configuration from an i-have-adhd.json file located in the agent's root directory (the folder returned by getAgentDir()). The AdhdConfig interface defined in extensions/i-have-adhd.ts (lines 37-40) supports the following properties:

alwaysOn

The alwaysOn boolean property controls automatic activation. When set to true, ADHD-friendly rules are injected automatically for every session without requiring manual enablement.

• Type: boolean
• Default: false
• Effect: Enables ADHD mode automatically at startup

hideStatus

The hideStatus boolean property controls UI verbosity. When set to true, the console suppresses the status indicator ("● ADHD ON") for cleaner output.

• Type: boolean
• Default: false
• Effect: Hides the ADHD mode status badge from the interface

Create the configuration file with these options:

{
  "alwaysOn": true,
  "hideStatus": true
}

Place this file at <agent-root>/i-have-adhd.json (for example, ~/my-pi-agent/i-have-adhd.json). The next time Pi starts, the skill activates automatically without displaying the status indicator.

Command-Line Configuration

For session-specific activation without modifying persistent configuration files, Pi supports the --adhd flag registered via pi.registerFlag("adhd", …) in extensions/i-have-adhd.ts.

Enable the skill for a single run:

pi run --adhd

This sets config.alwaysOn to true for that invocation only, overriding the JSON file's default value. The flag takes precedence over file-based configuration.

Interactive Runtime Controls

The extension registers interactive commands via pi.registerCommand("i-have-adhd", …) (lines 87-99 in extensions/i-have-adhd.ts) that allow toggling the mode during active sessions.

Toggle ADHD mode interactively:

/i-have-adhd          # toggles the current state

/i-have-adhd on       # forces the mode on

/i-have-adhd off      # forces the mode off

These commands modify the active session state immediately without updating the configuration file.

Configuration Architecture

Understanding how Pi resolves settings helps troubleshoot deployment issues.

File Resolution Path

The configuration loader searches for i-have-adhd.json in the directory returned by getAgentDir(). This ensures agent-specific settings remain isolated from global Pi installations.

Configuration Precedence

Settings resolve in the following priority order:

1. Command-line flags (--adhd) — highest priority
2. Interactive session toggles (/i-have-adhd commands)
3. JSON configuration file values (i-have-adhd.json)
4. Default values (both properties default to false) — lowest priority

Source Files

• extensions/i-have-adhd.ts — Implements the extension loader, configuration parsing, flag registration, and command handlers
• skills/i-have-adhd/SKILL.md — Contains the actual ADHD-friendly rule set injected into conversations when enabled

Summary

• The i-have-adhd skill supports two JSON configuration properties: alwaysOn for automatic activation and hideStatus for UI cleanup
• Configuration persists in <agent-root>/i-have-adhd.json resolved via getAgentDir()
• The --adhd CLI flag forces enablement for single sessions, overriding file settings
• Interactive commands (/i-have-adhd) provide runtime toggling without file modification
• All configuration logic resides in extensions/i-have-adhd.ts according to the AdhdConfig type definition

Frequently Asked Questions

Where do I place the i-have-adhd.json configuration file?

Place the file in your agent's root directory—the same folder returned by getAgentDir(). For example, if your agent lives at ~/my-pi-agent/, the full path should be ~/my-pi-agent/i-have-adhd.json. Pi loads this file at startup to populate the AdhdConfig settings.

Can I enable the i-have-adhd skill for just one session?

Yes. Use the --adhd command-line flag when running Pi: pi run --adhd. This flag temporarily sets config.alwaysOn to true for that specific invocation without modifying your i-have-adhd.json file or affecting future sessions.

What happens if both the config file and CLI flag conflict?

The CLI flag takes precedence. If your i-have-adhd.json sets "alwaysOn": false but you run pi run --adhd, the skill activates because command-line flags override JSON configuration values according to the precedence hierarchy in extensions/i-have-adhd.ts.

How do I hide the "ADHD ON" status indicator in the UI?

Set the hideStatus property to true in your i-have-adhd.json file. This boolean option suppresses the "● ADHD ON" badge that normally appears in the console output, providing a cleaner interface while maintaining full skill functionality.

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