# STATE_ENTRY_TYPE and Custom State Persistence in i-have-adhd

> Discover STATE_ENTRY_TYPE in i-have-adhd. Learn how this constant enables custom state persistence for the ADHD-mode flag, ensuring seamless session restoration.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-08-19

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), the extension defines a constant that acts as a unique discriminator for its session data:

```ts
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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) handles both the mode change and its persistence:

```ts
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:

```ts
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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts) and rule definitions in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), which defines `STATE_ENTRY_TYPE`, the `setEnabled` writer, and the `restoreState` reader. Companion utilities in [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts) handle context synchronization, while [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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.