How Configuration Is Managed in the i-have-adhd Project: A Complete Guide

The i-have-adhd extension manages configuration through a JSON file located in the agent directory, supporting optional alwaysOn and hideStatus boolean flags, while also respecting command-line flags and sentinel files for flexible runtime behavior.

The ayghri/i-have-adhd project implements a lightweight, file-based configuration system that prioritizes simplicity and user control. Unlike complex configuration managers that require databases or environment variables, this extension reads settings from a single JSON file adjacent to its installation directory, merging static preferences with dynamic runtime signals to determine activation state. Understanding how configuration is managed in this project requires examining the loading mechanism, supported options, and the precedence logic that resolves conflicting signals.

Configuration File Location and Loading Mechanism

The extension discovers its settings through the loadConfig() function defined in extensions/i-have-adhd.ts. This utility constructs the file path by joining the agent root directory—retrieved via getAgentDir()—with the filename i-have-adhd.json.

const config = JSON.parse(
  readFileSync(join(getAgentDir(), "i-have-adhd.json"), "utf8")
);

If the file does not exist or contains malformed JSON, the function returns an empty object {}, ensuring that every setting remains optional and the extension fails gracefully. This design allows the extension to run without any configuration file present, relying entirely on default behaviors and implicit signals.

Supported Configuration Options

The AdhdConfig type defines a strict interface with only two recognized keys, keeping the configuration surface minimal and predictable:

• alwaysOn (boolean): When set to true, ADHD mode starts enabled for every new session regardless of user flags or previous session state.
• hideStatus (boolean): When set to true, the UI status badge indicating "ADHD ON" is suppressed from the interface.

Both values are accessed throughout extensions/i-have-adhd.ts to initialize the default enabled state and control visibility of the status indicator. The type system ensures that no unrecognized keys affect runtime behavior.

Implicit Configuration Signals

Beyond the JSON file, the extension monitors two additional implicit signals that influence activation:

Agent Command-Line Flag: The extension registers "adhd" as a supported flag via pi.registerFlag("adhd", …), allowing users to start sessions with the --adhd option or equivalent UI toggle. This flag defaults to false when not specified.

Hidden Sentinel File: The existence of a hidden file named .i-have-adhd-always (created manually by the user in the agent directory) functions as a silent configuration trigger equivalent to setting alwaysOn: true in the JSON file.

Configuration Precedence and Resolution Logic

During session initialization, the extension resolves the effective "enabled-by-default" state through a specific precedence chain defined in extensions/i-have-adhd.ts. The runtime evaluates signals in the following order:

const enabledByDefault =
    pi.getFlag("adhd") === true ||
    config.alwaysOn === true ||
    existsSync(alwaysOnFlag);

The boolean logic ensures that any affirmative signal activates the mode. The agent flag takes precedence logically, though the OR structure means the mode activates if any source is true. The status UI displays only when enabled && !config.hideStatus, allowing users to run the mode invisibly when hideStatus is enabled.

Practical Configuration Examples

Enabling via JSON Configuration

Create an i-have-adhd.json file in your agent directory (e.g., ~/.config/instagit/agents/i-have-adhd/) to enable the mode by default and hide the UI badge:

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

With this configuration, ADHD mode activates for every session without displaying the status indicator.

Enabling via Sentinel File

For users who prefer file-based toggles without editing JSON, create an empty sentinel file:

touch ~/.config/instagit/agents/i-have-adhd/.i-have-adhd-always

This achieves the same effect as setting "alwaysOn": true in the configuration file, but requires no JSON syntax and can be quickly removed to disable the default behavior.

Runtime Configuration Overrides

While the JSON file controls default states, users can toggle the mode dynamically during active sessions using runtime commands:

// Disable ADHD mode immediately
await pi.runCommand("i-have-adhd", "off");

// Re-enable ADHD mode
await pi.runCommand("i-have-adhd", "on");

These commands persist session state separately from the static configuration file, allowing temporary overrides without modifying i-have-adhd.json.

Summary

• File-based configuration: The extension reads i-have-adhd.json from the agent directory via loadConfig(), falling back to an empty object if missing.
• Minimal schema: Only alwaysOn and hideStatus booleans are supported, defined by the AdhdConfig type.
• Multiple activation methods: Users can enable the mode via JSON settings, the --adhd agent flag, or a .i-have-adhd-always sentinel file.
• OR-based resolution: The effective state evaluates flag || config.alwaysOn || sentinelFile, activating if any source is true.
• UI control: The hideStatus option suppresses the "ADHD ON" badge independently of the activation state.

Frequently Asked Questions

Where does the i-have-adhd extension look for its configuration file?

The extension looks for i-have-adhd.json inside the agent installation directory, which getAgentDir() resolves at runtime (typically located at ~/.config/instagit/agents/i-have-adhd/ on Unix systems). The loadConfig() function in extensions/i-have-adhd.ts handles this path resolution automatically.

What happens if the JSON configuration file contains syntax errors?

If i-have-adhd.json cannot be parsed or does not exist, loadConfig() returns an empty object {} rather than throwing an error. This ensures the extension remains functional with default settings, treating all configuration options as undefined or false depending on the context.

How does the .i-have-adhd-always file interact with the alwaysOn JSON setting?

Both methods serve identical functions and are evaluated with logical OR logic. If either the alwaysOn JSON key is true or the .i-have-adhd-always file exists, the extension treats the configuration as "always on." The sentinel file provides a quick, scriptable alternative to editing JSON for users who prefer filesystem-based toggles.

Can I change configuration settings while the extension is running?

Changes to i-have-adhd.json or the sentinel file affect new sessions immediately, but runtime state is controlled separately through pi.runCommand("i-have-adhd", "on|off"). To persist changes across restarts, modify the JSON file; to change behavior temporarily within the current session, use the runtime commands.

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