Troubleshooting Guide: Debugging the i-have-adhd Plugin When It Fails to Load

When the i-have-adhd plugin fails to load, the root cause typically stems from five architectural layers: the extension entry point, rule file access, session state restoration, context synchronization, or command handling, each producing distinct error symptoms that require specific diagnostic steps.

The i-have-adhd plugin is a Pi-Coding-Agent extension that injects ADHD-friendly response rules into the model's context. When troubleshooting loading failures in the ayghri/i-have-adhd repository, you must trace execution through the extension's registration flow, file system access, and session management logic to identify exactly where initialization breaks down.

Understanding the Plugin Architecture

The plugin operates across three core components defined in the source code. The extension entry point (extensions/i-have-adhd.ts) registers the /i-have-adhd command and loads the rule file. The rule file (skills/i-have-adhd/SKILL.md) contains the ten ADHD-friendly rules in Markdown format. Finally, session state management persists the enabled/disabled flag across conversation turns using getSavedState() and restoreState().

When any layer fails, the plugin either silently ignores the --adhd flag, throws file system errors, or fails to persist user preferences across session compactions.

Common Failure Points and Diagnostic Steps

Extension Entry Point Failures (extensions/i-have-adhd.ts)

The extension initializes in extensions/i-have-adhd.ts by calling loadRules() (lines 46-63) to read the skill file. If the plugin reports "Unable to load i-have-adhd rules" or the /i-have-adhd command is ignored, verify the SKILL_PATH constant correctly points to ../skills/i-have-adhd/SKILL.md.

Insert diagnostic logging immediately after the readFileSync call to confirm file access:

// In extensions/i-have-adhd.ts
function loadRules(): string {
  console.log("[i-have-adhd] Attempting to read rule file:", SKILL_PATH);
  const content = readFileSync(SKILL_PATH, "utf8");
  console.log("[i-have-adhd] Rule file size:", content.length);
  return stripFrontmatter(content);
}

If the console remains silent, the extension was not discovered by Pi—check that package.json correctly lists the entry point under the "pi" configuration.

Rule File Access Errors (SKILL.md)

The skills/i-have-adhd/SKILL.md file must be readable and non-empty. When readFileSync throws ENOENT or returns an empty string, the extension triggers "The i-have-adhd rules file is empty" errors.

Check three specific conditions:

• The repository contains the file at the exact relative path from the extension's execution context
• The file contains actual rule content and not just YAML front-matter that the stripFrontmatter regex fails to remove
• File system permissions allow the agent's user to read the markdown file

Session State Restoration Issues

The plugin uses getSavedState() (lines 69-78) to read the i-have-adhd-state entry from the session manager. If the plugin always starts disabled despite the --adhd flag, inspect the sessionManager.getBranch() loop for correct type checking against customType === STATE_ENTRY_TYPE.

Confirm the extension registers the flag properly:

// Lines 63-67 in extensions/i-have-adhd.ts
pi.registerFlag("adhd", {
  description: "Enable ADHD-friendly response mode",
  default: false
});

If getSavedState() returns undefined consistently, verify STATE_ENTRY_TYPE is not misspelled in either the storage or retrieval logic.

Context Synchronization Problems

The syncContext() function ensures rule messages appear exactly once in the conversation context using latestMarkerIsActive from context-compat.ts. When rules duplicate after injections or disappear after session compaction, check that RULES_MESSAGE_TYPE and DISABLED_MESSAGE_TYPE constants are used consistently throughout the synchronization logic.

Command Handling Failures

The /i-have-adhd command handler (lines 69-91) toggles the mode on/off. If the command produces "Usage: /i-have-adhd [on|off]" errors when typed correctly, or the UI fails to show the "● ADHD ON" badge, examine the handler logic:

// Verify in extensions/i-have-adhd.ts
const arg = args.trim().toLowerCase();
if (arg === "on") {
  await setEnabled(true);
  ctx.ui.notify("ADHD mode enabled", "success");
}

Ensure setEnabled calls both pi.appendEntry to persist state and ctx.ui.notify to update the interface.

Step-by-Step Debugging Procedure

Follow this systematic approach to isolate the failure layer:

1. Verify extension loading by adding console.log("i-have-adhd extension loaded") at the top of extensions/i-have-adhd.ts. If the message does not appear in the agent's console, the extension entry point is not registered.

2. Check rule-file loading by logging the output of loadRules(). If exceptions occur, adjust SKILL_PATH or restore the missing SKILL.md file.

3. Confirm UI status updates by adding debug output in updateStatus to print the enabled boolean after toggling the mode with /i-have-adhd on.

4. Inspect session persistence by logging the output of getSavedState(ctx). If always undefined, the custom entry type constant is likely inconsistent between save and load operations.

5. Validate context markers using the helper from context-compat.ts:

const present = rulesAreInContext(ctx);
console.log("Rules currently in context?", present);

If present toggles unexpectedly after compaction, latestMarkerIsActive may mis-identify the newest marker.

6. Run minimal reproduction by creating a fresh session, enabling the mode, issuing a request, then triggering session_compact to observe if rules persist through the compaction event.

Diagnostic Code Snippets

Manually Trigger Context Sync

// In a test script or REPL
await pi.sendMessage(
  { customType: "i-have-adhd-sync", content: "", display: false },
  { triggerTurn: false }
);

Verify UI Badge Rendering

// After enabling the mode
pi.sendMessage(
  { customType: "i-have-adhd-test", content: "test", display: false },
  { triggerTurn: false }
);
// Expected: Green "● ADHD ON" appears in status bar

Check Session Entry Type

// Debug state restoration
const saved = getSavedState(ctx);
console.log("Restored saved state:", saved);
console.log("Entry type constant:", STATE_ENTRY_TYPE);

Summary

• Extension loading failures indicate missing entry point registration or incorrect package.json configuration in ayghri/i-have-adhd.
• Rule file errors trace to SKILL_PATH misconfiguration, missing skills/i-have-adhd/SKILL.md, or front-matter stripping failures in loadRules().
• State persistence issues stem from STATE_ENTRY_TYPE inconsistencies between getSavedState() and the session manager.
• Context duplication results from improper latestMarkerIsActive logic or mismatched RULES_MESSAGE_TYPE constants.
• Command failures occur when args parsing or setEnabled implementation lacks proper trimming, lowercasing, or UI notification calls.

Frequently Asked Questions

Why does the i-have-adhd plugin report "Unable to load i-have-adhd rules" on startup?

This error originates in the loadRules() function (lines 46-63) in extensions/i-have-adhd.ts when readFileSync cannot locate SKILL.md at the relative path defined by SKILL_PATH. Verify the file exists at skills/i-have-adhd/SKILL.md relative to the extension's execution directory, and ensure the path separator syntax matches your operating system.

Why does the plugin disable itself after session compaction?

The syncContext() function relies on latestMarkerIsActive in context-compat.ts to determine if rules are present. If rules disappear after compaction, the marker detection logic may fail to identify the most recent context entry, causing the extension to believe the rules are absent. Check that RULES_MESSAGE_TYPE matches exactly between the injection and detection code.

Why does the /i-have-adhd on command show usage instructions instead of enabling the mode?

The command handler (lines 69-91) validates arguments by trimming and lowercasing the input before comparison. If the argument parsing fails, the handler falls back to usage instructions. Ensure no invisible characters or extra whitespace precede your command, and verify that args.trim().toLowerCase() is being called before the equality check against "on" or "off".

How do I verify the plugin is actually loading without visible errors?

Add console.log("[i-have-adhd] Extension initialized") at the top level of extensions/i-have-adhd.ts immediately after imports. If this log does not appear when the agent starts, Pi has not discovered the extension—check your package.json "pi" entry points array to confirm the file path is registered correctly.

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