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

> Discover how the i-have-adhd project manages configuration using JSON files, command-line flags, and sentinel files for flexible and efficient operation.

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

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.json).

```typescript
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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts). The runtime evaluates signals in the following order:

```typescript
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`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```json
{
  "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:

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

```typescript
// 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`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.json).

## Summary

- **File-based configuration**: The extension reads [`i-have-adhd.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.