# How to Create Custom Cognitive Frames for ADHD: A Complete Guide

> Learn how to create custom cognitive frames for ADHD by defining Frame objects and adding them to the FRAMES array in src/frames.ts. Master your focus with this complete guide.

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

---

**You create custom cognitive frames for ADHD by defining a `Frame` object with a unique `id`, `label`, `prompt`, and `tags`, then appending it to the `FRAMES` array in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts).**

The ADHD framework generates **cognitive diversification** by injecting perspective-shifting prompts—called *frames*—into AI generation passes. These frames are statically defined TypeScript objects that reframe problems through different professional or philosophical lenses. Because the frame registry loads at import time, adding custom perspectives requires only a quick edit to the source code, with no runtime configuration or service restarts needed.

## Understanding the Frame Architecture

The ADHD framework maintains its frame collection in **[`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts)**, where the `Frame` interface and the exported `FRAMES` constant reside. According to the source code, a `Frame` object requires four properties:

- **`id`**: A unique string identifier (e.g., `"quantum-physicist"`)
- **`label`**: A human-readable name displayed in output
- **`prompt`**: The system-prompt fragment injected to shift perspective
- **`tags`**: An array of strings (e.g., `"code"`, `"design"`, `"general"`, `"wild"`) used by the selection algorithm

During execution, the **`selectFrames()`** function in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) randomly selects a subset from the `FRAMES` array. When `codeMode` is enabled, the selector biases toward entries tagged with `"code"`, while the `"wild"` tag guarantees diversity by ensuring the frame appears in randomized selections.

## Step-by-Step Guide to Creating Custom Cognitive Frames

### Define the Frame Object

Create a TypeScript object conforming to the `Frame` interface. The `prompt` field should contain specific instructions that re-ask the problem from your desired perspective.

### Register the Frame

Append your object to the `FRAMES` array exported from [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts). Because this array is imported statically by the engine, the new frame becomes available immediately upon the next execution.

### Configure Tags for Selection Behavior

Choose tags strategically to control when your frame appears:

- **`"code"`**: Prioritized when running with `codeMode: true`
- **`"design"`**: Targets creative and UX-oriented generation passes
- **`"general"`**: Suitable for broad, non-technical reasoning
- **`"wild"`**: Forces inclusion in random selections to guarantee cognitive diversity

## Practical Code Examples

### Adding a Domain-Specific Frame

The following example adds a "Quantum Physicist" frame to [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts). This frame instructs the AI to consider superposition and probabilistic outcomes:

```typescript
// src/frames.ts – append to the FRAMES array
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"],   // appears in code‑mode and guarantees diversity
  },
];

```

### Programmatic Frame Selection

After modifying [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts), your custom frame automatically enters the selection pool. Use the `selectFrames` utility to test the integration:

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

// Request 3 frames with codeMode enabled
const chosen = selectFrames(3, true);
console.log(chosen.map(f => f.label));
/* Example output:
   [
     "Hardware engineer",
     "Quantum Physicist",   // custom frame appears automatically
     "Inversion"
   ]
*/

```

### Using Custom Frames via CLI

The command-line interface exposes frame selection through the `--frames` option. After saving your changes to [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts), the next CLI invocation immediately recognizes the new perspective:

```bash

# Request 4 cognitive frames; custom frames are eligible for selection

npx adhd run --frames 4

```

## Key Implementation Details

The frame system relies on two critical source files:

- **[`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts)**: Defines the `Frame` type (lines 5–22) and the `FRAMES` constant (lines 16–22). This is the only file you modify when adding custom frames.
- **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)**: Houses the `selectFrames` function that implements the random selection logic with tag-based weighting.

Because the framework uses static imports rather than dynamic registration, the `FRAMES` array is frozen at startup. This design eliminates runtime overhead but means you must edit the source file and save changes before new frames become active.

## Summary

- **Custom cognitive frames for ADHD** are defined as TypeScript objects implementing the `Frame` interface in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts).
- Each frame requires a unique `id`, descriptive `label`, perspective-shifting `prompt`, and strategic `tags` array.
- The `selectFrames()` function in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) handles random selection with bias toward `"code"` tags when `codeMode` is enabled.
- No runtime registration is required; append to the `FRAMES` array and the next CLI or library execution automatically includes your custom perspective.

## Frequently Asked Questions

### What properties must a custom Frame object include?

A valid `Frame` object must include four properties: `id` (unique string identifier), `label` (display name), `prompt` (the system instruction injected into the generation context), and `tags` (array of category strings). These are defined in the `Frame` interface located in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) at lines 5–22.

### How does the engine decide which custom frames to use?

The `selectFrames()` function in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) performs a randomized selection from the `FRAMES` array. If the `codeMode` parameter is `true`, the algorithm weights entries tagged with `"code"` more heavily during the shuffle. Tags like `"wild"` force inclusion to ensure cognitive diversity across generation passes.

### Do I need to restart the CLI after adding a new frame?

No additional restart or runtime registration is required. Because [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) exports the `FRAMES` constant statically, simply saving the file with your new frame object makes it available to the next execution of the CLI or any script importing the library.

### Can I create frames specifically for software engineering tasks?

Yes. Tag your custom frame with `"code"` to ensure it receives priority when `codeMode` is enabled. You can combine multiple tags—for example, `["code", "wild"]`—to indicate the frame applies to technical problems while also guaranteeing it appears regularly in randomized selections for maximum cognitive diversification.