STATE_ENTRY_TYPE and Custom State Persistence in i-have-adhd

In the ayghri/i-have-adhd extension, STATE_ENTRY_TYPE is the string constant "i-have-adhd-state" that labels custom session entries, enabling the Pi Coding Agent to persist and restore the ADHD-mode flag across session lifecycles.

The ayghri/i-have-adhd repository implements a Pi Coding Agent extension that must remember whether ADHD mode is enabled between session restarts. Instead of relying on external storage, the extension uses the session manager's branch-based entry system through the STATE_ENTRY_TYPE identifier. This mechanism lets the extension write a small payload containing the enabled boolean and later recover that exact state when the session resumes.

What Is STATE_ENTRY_TYPE?

Inside extensions/i-have-adhd.ts, the extension defines a constant that acts as a unique discriminator for its session data:

const STATE_ENTRY_TYPE = "i-have-adhd-state";

Whenever the extension persists state, this value is assigned to the entry's customType field. Because the Pi Coding Agent's session manager stores many kinds of entries, STATE_ENTRY_TYPE guarantees that only entries belonging to this extension are recognized during state recovery.

How Custom State Is Persisted in i-have-adhd

The extension follows a write-and-read pattern against the current session branch. When a user toggles ADHD mode, the extension appends a new custom entry. When the session restarts, a helper walks the branch history to locate the latest matching entry.

Writing State with pi.appendEntry

The setEnabled function in extensions/i-have-adhd.ts handles both the mode change and its persistence:

const setEnabled = (nextEnabled: boolean, ctx: ExtensionContext): void => {
  enabled = nextEnabled;
  pi.appendEntry(
    STATE_ENTRY_TYPE,
    { enabled } satisfies AdhdModeState
  );
  updateStatus(ctx);
  syncContext(ctx);
  ctx.ui.notify(`ADHD mode ${enabled ? "enabled" : "disabled"}`, "info");
};

Here, pi.appendEntry writes an entry whose customType is set to STATE_ENTRY_TYPE and whose payload carries the enabled boolean. The entry becomes part of the session branch, making it available for later retrieval without external file I/O.

Retrieving State with getSavedState

On session startup, the restoreState function calls getSavedState to recover the previous flag. Internally, getSavedState requests the current branch via ctx.sessionManager.getBranch() and scans the entries. It filters for items whose type is "custom" and whose customType matches STATE_ENTRY_TYPE, then extracts the latest enabled value from the matching payload.

The restoreState function then applies this value or falls back to defaults:

const restoreState = (ctx: ExtensionContext): void => {
  const savedState = getSavedState(ctx);
  const enabledByDefault =
    pi.getFlag("adhd") === true || existsSync(alwaysOnFlag);

  enabled = savedState ?? enabledByDefault;
  updateStatus(ctx);
  syncContext(ctx);
};

If a persisted entry exists, the extension restores that exact boolean. Otherwise, it derives the initial state from pi.getFlag("adhd") or the presence of an alwaysOnFlag file on disk.

Context Synchronization Across Files

The file extensions/context-compat.ts supplies additional helpers such as latestMarkerIsActive that work alongside these custom entries. These utilities keep the conversation context in sync with the persisted ADHD mode, ensuring that rule sets defined in skills/i-have-adhd/SKILL.md are applied consistently whenever the mode is active.

Summary

• STATE_ENTRY_TYPE is defined as "i-have-adhd-state" in extensions/i-have-adhd.ts and serves as the unique customType for the extension's session entries.
• The extension writes state by calling pi.appendEntry with STATE_ENTRY_TYPE and an { enabled } payload.
• The extension reads state via getSavedState, which scans the current branch for custom entries matching the identifier.
• If no persisted state is found, restoreState falls back to flag checks and file-system markers.
• Supporting logic in extensions/context-compat.ts and rule definitions in skills/i-have-adhd/SKILL.md ensure the mode remains synchronized with the active conversation context.

Frequently Asked Questions

What is the purpose of STATE_ENTRY_TYPE in i-have-adhd?

STATE_ENTRY_TYPE is a constant string that tags custom entries in the Pi Coding Agent's session manager. It ensures the extension can distinguish its own state entries from other session data when saving or restoring the ADHD-mode flag.

How does getSavedState locate the persisted custom state?

getSavedState requests the current branch from ctx.sessionManager.getBranch(), then filters the entry list for items where type === "custom" and customType === STATE_ENTRY_TYPE. It extracts the most recent enabled boolean from the matching payload.

Where is the persistence logic implemented?

The core persistence logic resides in extensions/i-have-adhd.ts, which defines STATE_ENTRY_TYPE, the setEnabled writer, and the restoreState reader. Companion utilities in extensions/context-compat.ts handle context synchronization, while skills/i-have-adhd/SKILL.md stores the rule set applied when the mode is enabled.

What happens if no custom state entry exists in the session branch?

If getSavedState returns no result, restoreState falls back to alternative sources. It checks whether pi.getFlag("adhd") is true or whether an alwaysOnFlag file exists on disk, then initializes the mode using those defaults.

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