Troubleshooting i-have-adhd Not Activating in Autocomplete: Complete Fix Guide

The i-have-adhd extension typically fails to activate during autocomplete when the always-on marker file is missing, the hook script fails to execute, or stale context state flags prevent the syncContext() function from injecting rules into the language model.

The i-have-adhd extension enhances AI coding assistants by injecting ADHD-friendly communication guidelines into the context window, but users frequently encounter issues where these modifications fail to appear during autocomplete sessions. According to the ayghri/i-have-adhd source code, the extension relies on specific state management mechanisms in extensions/i-have-adhd.ts to persist activation across sessions. Understanding how restoreState() evaluates session entries and how syncContext() handles rule injection is essential for diagnosing why the behavior doesn't carry over between autocomplete turns.

Common Symptoms and Root Causes

No ADHD Rules Appear After Manual Activation

If you run /i-have-adhd on but see no evidence of ADHD-friendly formatting in autocomplete suggestions, the always-on flag file is likely missing. The extension checks for a marker file named .i-have-adhd-always in the agent directory to determine whether to activate automatically at session start.

Create this file manually to enable persistent activation:

# In the agent's root directory (where agent.json lives)

touch .i-have-adhd-always

Alternatively, ensure the hooks/always-on.mjs script is executable and properly configured to run at session initialization. This hook automatically registers the extension without requiring manual commands.

Chat Commands Work but Autocomplete Ignores Rules

When the /i-have-adhd command functions in the chat interface but autocomplete remains unaffected, the extension likely failed to inject rules because rulesAreInContext() returned false. According to lines 22-33 in extensions/i-have-adhd.ts, this occurs when a previous session injected a disabled marker that persists in the context window, causing syncContext() to skip rule insertion.

Reset the context state by toggling the extension off and on:

/i-have-adhd off
/i-have-adhd on

This forces the extension to clear stale entries and re-inject the ruleset from skills/i-have-adhd/SKILL.md.

"Unable to Load i-have-adhd Rules" Errors

Errors indicating the rules cannot load point to a corrupted or missing SKILL.md file. As implemented in lines 42-59 of extensions/i-have-adhd.ts, the loadRules() function reads this file and strips its front-matter before caching the content.

Verify the file exists and is readable:

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

If this file is absent or inaccessible, the extension cannot populate the context with ADHD-friendly guidelines.

How the Extension Activates in Autocomplete

State Restoration Mechanism

The restoreState() function (lines 49-55 in extensions/i-have-adhd.ts) evaluates three conditions to determine activation:

• Saved Session Entry (STATE_ENTRY_TYPE): Persists across restarts if previously enabled
• Command-Line Flag (pi.getFlag("adhd")): Checks for the --adhd argument
• Always-On Marker: Detects the presence of .i-have-adhd-always file

If any condition returns true, the extension attempts to inject rules via syncContext().

Rule Injection and Context Synchronization

The syncContext() function manages the actual insertion and removal of rules. It first calls rulesAreInContext() to check if ADHD guidelines are already present. If enabled but missing, it sends a custom message of type i-have-adhd-rules to populate the context. If disabled, it sends i-have-adhd-disabled to remove them.

This mechanism ensures the ruleset from SKILL.md appears in every autocomplete turn when properly activated.

The Always-On Hook System

For autocomplete to work consistently, the hooks/always-on.mjs script must execute at session startup. This JavaScript hook (along with shell alternatives always-on.sh and always-on.ps1) mimics the manual /i-have-adhd on command automatically, ensuring the extension registers before any autocomplete requests occur.

The hook is essential because autocomplete operates before users can manually run chat commands.

Step-by-Step Resolution Guide

Follow this diagnostic sequence when troubleshooting i-have-adhd autocomplete failures:

1. Verify Plugin Registration: Confirm plugin.json contains the extension entry and is properly formatted. Without this registration, the host platform won't load the extension.

2. Check Rule File Accessibility: Ensure skills/i-have-adhd/SKILL.md exists and contains valid markdown. The loadRules() function depends on this file being readable.

3. Enable Always-On Mode: Create the marker file to persist activation across sessions:

   touch .i-have-adhd-always

4. Execute the Hook Script: Verify hooks/always-on.mjs runs at session start, or manually source the appropriate shell script (always-on.sh or always-on.ps1) for your environment.

5. Reset Context State: If rules appear corrupted, force a fresh injection:

   /i-have-adhd off
   /i-have-adhd on

6. Review Console Logs: Check for errors thrown by loadRules() or syncContext() that indicate file path issues or permission problems.

Summary

• The i-have-adhd extension requires the .i-have-adhd-always marker file or active hook script to activate during autocomplete sessions.
• The restoreState() function in extensions/i-have-adhd.ts checks session entries, command flags, and marker files to determine activation state.
• Rule injection depends on syncContext() detecting missing rules via rulesAreInContext() and sending the appropriate message type.
• Always verify that skills/i-have-adhd/SKILL.md exists and that plugin.json properly registers the extension.
• Toggle /i-have-adhd off followed by /i-have-adhd on to clear stale context states that prevent rule injection.

Frequently Asked Questions

Why does the extension work in chat but not in autocomplete?

Autocomplete sessions initialize before the chat interface loads, requiring the hooks/always-on.mjs script or .i-have-adhd-always marker file to trigger activation automatically. Without these mechanisms, the extension waits for manual commands that arrive too late for autocomplete context preparation.

How do I make i-have-adhd activate automatically for every session?

Create the always-on marker file in your agent directory using touch .i-have-adhd-always, or ensure the appropriate hook script (always-on.mjs, always-on.sh, or always-on.ps1) executes at session startup. This mimics running /i-have-adhd on before any autocomplete requests occur.

What should I do if I see "Unable to load i-have-adhd rules" errors?

This error indicates loadRules() cannot read skills/i-have-adhd/SKILL.md. Verify the file exists at that exact path, check file permissions to ensure readability, and confirm the markdown front-matter isn't corrupted, as the function strips this metadata before caching the rules.

How do I reset the extension when it seems stuck in a disabled state?

Run the toggle sequence /i-have-adhd off followed by /i-have-adhd on to force syncContext() to clear any disabled markers from the context window and re-inject fresh rules. If this fails, restart the session after confirming the always-on marker file is present.

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