# How to Troubleshoot i-have-adhd Not Activating or Not Appearing in Autocomplete

> Troubleshoot i-have-adhd activation issues. Learn why i-have-adhd may not appear in autocomplete or activate and find solutions for missing SKILL.md files, misconfigured manifests, and absent flag files.

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

---

**The i-have-adhd Pi extension fails to activate when the SKILL.md rules file is missing, the plugin manifest is misconfigured, or the always-on flag file is not present in the agent directory.**

The `i-have-adhd` extension for Pi-based agents enhances context management with ADHD-friendly rule sets, but users often encounter issues where the mode refuses to activate or the `/i-have-adhd` command disappears from autocomplete. This troubleshooting guide walks through the complete activation flow implemented in the `ayghri/i-have-adhd` repository, providing diagnostic steps and fixes rooted in the actual source code architecture.

## Understanding the Activation Architecture

Troubleshooting effectively requires knowing how the three core components interact to load rules and register commands.

### Extension Core in extensions/i-have-adhd.ts

The primary logic lives in **[`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)**, where the extension loads markdown rules from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), tracks the enabled state via the `adhd` flag, and manages context injection. On `session_start` or `session_tree` events, the `restoreState` function reads the persisted `i-have-adhd-state` entry and calls `syncContext` to inject either the ruleset (`i-have-adhd-rules`) or a disabled notice (`i-have-adhd-disabled`).

### Always-On Hook in hooks/always-on.mjs

The **`hooks/always-on.mjs`** script runs at every session start via the `SessionStart` hook declared in **[`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json)**. It checks for the hidden file `.i-have-adhd-always` in the agent directory and automatically sets the `adhd` flag to `true` if found, bypassing manual activation.

### Command Registration and Aliases

The extension registers the slash-command `/i-have-adhd` through `pi.registerCommand`, which aliases the built-in skill command `/skill:i-have-adhd`. When executed, the `setEnabled` function flips the internal boolean, persists the state via `i-have-adhd-state`, updates the UI badge, and triggers `syncContext` to refresh the conversation context.

## Diagnostic Symptoms and Root Causes

When `i-have-adhd` is not activating or missing from autocomplete, the issue typically falls into one of these four categories.

### No "ADHD ON" Status Badge Appears

If the status indicator never displays, the extension likely failed to load during initialization. Check that `SKILL_PATH` in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) correctly resolves to [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). If the markdown file is missing or the relative path is broken, the extension throws an initialization error before registering any UI components.

### Slash Command /i-have-adhd Does Nothing

When the command appears but fails to toggle the mode, the command registration may have partially failed or the extension initialization sequence was interrupted. Verify that `pi.registerCommand` executed without errors by inspecting the session logs for registration confirmations.

### Rules Not Injecting After Enabling

If the badge shows "ADHD ON" but the rules do not affect the model's behavior, the `syncContext` function in [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) may be failing. This function uses `latestMarkerIsActive` to determine whether the rules marker was overridden by a "disabled" notice or dropped during session compaction. Rules that disappear after several conversation turns indicate compaction is removing the `i-have-adhd-rules` marker from context.

### Missing from Autocomplete Suggestions

When the command does not appear in your IDE or editor's autocomplete, the plugin manifest ([`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) or [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json)) is likely missing the command definition in the `commands` array. The host runtime requires this manifest entry to expose the slash-command to the UI layer.

## Step-by-Step Troubleshooting Fixes

Resolve activation issues by systematically verifying each component.

### Verify the Rules File Location

The extension constructs the path to [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) relative to the extension directory. If you see "Unable to load i-have-adhd rules" errors:

```bash

# Verify the file exists at the expected location

ls -la skills/i-have-adhd/SKILL.md

# Check that SKILL_PATH resolves correctly in extensions/i-have-adhd.ts

# It should point to: <extension-dir>/skills/i-have-adhd/SKILL.md

```

### Check Plugin Manifest Configuration

Ensure the command is exposed to the host runtime by verifying your plugin manifest includes:

```json
{
  "commands": [
    {
      "name": "i-have-adhd",
      "description": "Toggle ADHD mode"
    }
  ]
}

```

For Claude Code specifically, check [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) for the commands array definition.

### Enable Always-On Mode

To force activation at every session start without manual commands:

```bash

# Create the hidden flag file in the agent directory

touch "$(pi get-agent-dir)/.i-have-adhd-always"

```

Check the console output for "Checking i-have-adhd always-on flag…" to confirm `hooks/always-on.mjs` executed successfully.

### Manual State Recovery via Flag

If the extension is stuck in a disabled state, manually set the flag at launch:

```bash

# Launch Pi with the adhd flag enabled

PI_FLAGS="adhd=true" pi

```

## Debugging with Code Examples

For advanced debugging, manually trigger context injection to verify the messaging layer works:

```typescript
// Within a Pi session script or debug console
pi.sendMessage(
  {
    customType: "i-have-adhd-rules",
    content: "ADHD MODE ACTIVE…\n\n" + loadRules(),
    display: false,
  },
  { triggerTurn: false }
);

```

To toggle the state programmatically:

```text
/i-have-adhd on   # Explicitly enable ADHD mode

/i-have-adhd off  # Explicitly disable ADHD mode

```

## Summary

- **Extension Core**: The activation logic resides in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), which manages the `adhd` flag and calls `syncContext` to inject rules.
- **Always-On Hook**: Create `.i-have-adhd-always` in the agent directory to auto-enable via `hooks/always-on.mjs` at session start.
- **Rules File**: Ensure [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) exists and `SKILL_PATH` resolves correctly to prevent load failures.
- **Manifest Requirements**: Autocomplete requires the command definition in [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) or [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json).
- **Context Persistence**: Rules may disappear after compaction; re-run `/i-have-adhd` to re-inject the marker if behavior changes mid-session.

## Frequently Asked Questions

### Why does the /i-have-adhd command disappear from autocomplete after restarting?

The command disappears when the plugin manifest is not loaded by the host runtime or the extension failed to initialize. Verify that [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) contains the command in the `commands` array and that [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) is not throwing errors during the `session_start` hook. Check the initialization logs for "registerCommand" confirmation messages.

### Why do ADHD rules stop working after several conversation turns?

The Pi context window compacts older messages to manage token limits, and the `i-have-adhd-rules` marker may be dropped during this process. According to the [`context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/context-compat.ts) implementation, if `latestMarkerIsActive` returns false because the rules marker was overridden by `i-have-adhd-disabled` or removed by compaction, the rules no longer affect the model. Re-enable the mode by running `/i-have-adhd on` to call `syncContext` and re-inject the marker.

### How do I check if the always-on flag is actually working?

The `hooks/always-on.mjs` script logs diagnostic output when checking for the flag file. Look for the console message "Checking i-have-adhd always-on flag…" at session start. If you do not see this message, verify that [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) correctly declares the `SessionStart` hook pointing to `hooks/always-on.mjs`, and ensure the `.i-have-adhd-always` file exists in the directory returned by `pi get-agent-dir`.

### What causes the "Unable to load i-have-adhd rules" error?

This error occurs when [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) cannot read [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) at the resolved `SKILL_PATH`. The path is built relative to the extension directory, so if the repository structure changed or the file was moved, the extension fails to load the rule set. Confirm the file exists at [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and that the extension has read permissions for that path.