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

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, where the extension loads markdown rules from 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. 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 correctly resolves to 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 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 or .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 relative to the extension directory. If you see "Unable to load i-have-adhd rules" errors:

# 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:

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

For Claude Code specifically, check .claude-plugin/plugin.json for the commands array definition.

Enable Always-On Mode

To force activation at every session start without manual commands:

# 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:

# 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:

// 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:

/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, 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 exists and SKILL_PATH resolves correctly to prevent load failures.
• Manifest Requirements: Autocomplete requires the command definition in plugin.json or .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 contains the command in the commands array and that 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 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 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 cannot read 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 and that the extension has read permissions for that path.

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