# How to Add Custom Cognitive Frames to the ADHD Framework: A Complete Guide

> Learn to add custom cognitive frames to the ADHD framework. This guide shows you how to create and integrate new frames for enhanced functionality. Explore the UditAkhourii/adhd repository.

- Repository: [Udit Akhouri/adhd](https://github.com/UditAkhourii/adhd)
- Tags: how-to-guide
- Published: 2026-07-30

---

**To add custom cognitive frames to the ADHD framework, create a Frame object with a unique id, descriptive label, system prompt text, and relevant tags, then append it to the exported FRAMES array in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts).**

The ADHD framework, available in the UditAkhourii/adhd repository, drives cognitive diversification through *frames*—small prompt snippets that re-ask problems from different perspectives. Learning how to add custom cognitive frames to the ADHD framework allows you to inject domain-specific thinking modes directly into the generation pipeline controlled by [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts).

## Understanding the Frame Architecture

According to the UditAkhourii/adhd source code, the `Frame` type is defined in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) (lines 5-22) with four required properties: `id` (unique string identifier), `label` (human-readable name), `prompt` (the system-prompt fragment injected during generation), and `tags` (array of strings influencing selection weight).

The framework exports a constant `FRAMES` array containing all available frame objects. During execution, the `selectFrames()` function in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) randomly samples from this array, biasing toward entries tagged with `"code"` when code mode is enabled. Because frames load statically at import time, no additional configuration or runtime registration is required.

## Step-by-Step: Adding a Custom Cognitive Frame

### Step 1: Define the Frame Object

Create a new `Frame` object that encapsulates your desired cognitive perspective. Ensure the `id` is unique across the existing `FRAMES` array.

```typescript
// Frame definition example
const quantumFrame = {
  id: "quantum-physicist",
  label: "Quantum Physicist",
  prompt: "You think like a quantum physicist: consider superposition, entanglement, and probabilistic outcomes. Re‑ask the problem as if the solution could exist in multiple states simultaneously.",
  tags: ["code", "wild"]
};

```

### Step 2: Append to the FRAMES Array

Register your frame by adding the object to the exported `FRAMES` array in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts). This makes it available to the selector immediately upon the next execution.

```typescript
// src/frames.ts
export const FRAMES: Frame[] = [
  // …existing frames…

  {
    id: "quantum-physicist",
    label: "Quantum Physicist",
    prompt: "You think like a quantum physicist: consider superposition, entanglement, and probabilistic outcomes. Re‑ask the problem as if the solution could exist in multiple states simultaneously.",
    tags: ["code", "wild"]
  },
];

```

### Step 3: Verify Frame Selection

Test your implementation by calling `selectFrames()` from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts). The function will now consider your custom entry when shuffling the pool.

```typescript
import { selectFrames } from "./engine";

// Request 3 frames; codeMode=true prefers "code" tags
const chosen = selectFrames(3, true);
console.log(chosen.map(f => f.label));
/* Example output:
   [
     "Hardware engineer",
     "Quantum Physicist",
     "Inversion"
   ]
*/

```

## Frame Tagging and Selection Logic

Tags control how `selectFrames()` weights frames during random sampling. The implementation in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) recognizes specific strings that alter selection probability:

- **`"code"`**: Biased toward when the second parameter of `selectFrames()` is `true`
- **`"wild"`**: Guarantees diversity by marking the frame as a wildcard entry
- **`"design"`** and **`"general"`**: Alternative categories for specific contexts

Include multiple tags to increase selection likelihood across different modes. The engine specifically checks for the `"code"` tag to determine weighting during code mode operations.

## Running Custom Frames via CLI

After modifying [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts), the ADHD CLI automatically recognizes new frames. Use the `--frames` flag to specify how many perspectives the engine should sample.

```bash

# Request 4 cognitive frames; custom entries may appear

npx adhd run --frames 4

```

The CLI in [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) internally calls `selectFrames()`, passing the count and mode preferences to the engine.

## Summary

- **Frame objects** require `id`, `label`, `prompt`, and `tags` properties as defined in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts).
- **Registration** occurs by appending to the exported `FRAMES` array; no runtime registration is necessary due to static imports.
- **Selection logic** resides in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) within the `selectFrames()` function, which respects tag weighting for code mode and wildcards.
- **Immediate availability** means changes to [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) are reflected in the next CLI execution or library import.

## Frequently Asked Questions

### Do I need to rebuild the project after adding a custom frame?

No. Because [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) exports `FRAMES` as a statically imported constant, the framework loads frames at import time. Simply save the modified TypeScript file and the next execution of the CLI or library import will automatically include your new frame in the selection pool.

### What happens if two frames share the same id?

While the source code does not enforce uniqueness constraints at runtime, duplicate `id` values may cause ambiguity in logging and potential conflicts if the framework implements future caching mechanisms. Always ensure your frame's `id` is unique among entries in the `FRAMES` array.

### How do tags affect the probability of frame selection?

The `selectFrames()` function in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) uses tags to weight random selection. When the second parameter is `true` (code mode), the selector biases toward frames tagged with `"code"`. The `"wild"` tag guarantees inclusion for diversity purposes. Multiple tags increase a frame's eligibility across different runtime configurations.

### Can I create frames without any tags?

Yes, frames can include an empty tags array, but they will receive no selection bias during the random sampling process. Untagged frames compete equally with all other entries, making them less likely to appear in code-specific contexts where the engine actively prefers tagged alternatives.