# How to Integrate ADHD into a Custom Agent Framework: Complete Implementation Guide

> Integrate ADHD into your custom agent framework with ease. Install the adhd agent package and use the run function to configure problem context frame count and concurrency for seamless implementation.

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

---

**You can integrate the ADHD agent into any custom Node.js-based agent framework by installing the `adhd-agent` package and invoking the `run` function from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) with a `RunOptions` configuration object that specifies problem context, frame count, and concurrency settings.**

The ADHD repository by UditAkhourii provides a self-contained NPM package (`adhd-agent`) and a ready-to-use skill definition ([`skills/adhd/SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md)) designed to enhance LLM agents with structured divergent thinking. Whether you are building a custom orchestrator from scratch or extending an existing platform like Claude Code or Repowire, you can integrate ADHD into a custom agent framework using either the JavaScript library API or the declarative skill interface.

## Installation and Package Setup

To begin, install the package via NPM:

```bash
npm install adhd-agent

```

Alternatively, for skill-based integration, download the skill definition directly into your agent's skill directory:

```bash
mkdir -p ~/.myagent/skills/adhd
curl -fsSL https://raw.githubusercontent.com/UditAkhourii/adhd/main/skills/adhd/SKILL.md \
  -o ~/.myagent/skills/adhd/SKILL.md

```

The library exposes its core API from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), while cognitive frames are defined in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) and type declarations live in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts).

## Core Integration via the Engine API

The primary entry point for integrating ADHD into a custom agent framework is the **`run`** function exported from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts). This function orchestrates the complete reasoning loop: reframing, divergence, scoring, clustering, and deepening.

The function accepts a **`RunOptions`** object containing:

- **`problem`** (string): The problem statement or user prompt
- **`context`** (optional): Additional context for the LLM
- **`framesPerRun`** (number): How many cognitive frames to invoke
- **`ideasPerFrame`** (number): Ideas generated per frame
- **`topK`** (number): Number of ideas to deepen
- **`codeMode`** (boolean): Whether to bias frames toward code-centric topics
- **`concurrency`** (number): Parallel LLM calls for performance

The function returns a **`RunResult`** object (defined in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)) containing:
- **`branches`**: Raw ideas generated per frame
- **`clusters`**: Semantic groupings of ideas
- **`shortlist`**: Top-ranked ideas by critic score
- **`nonObviousPick`**: The most novel viable suggestion
- **`traps`**: Flagged risky ideas with trap scores
- **`deepened`**: Expanded sketches for the top-K picks
- **`provocation`**: A wildcard prompt for continued brainstorming

## Integration Patterns

### Pattern 1: Direct Library Usage

The simplest way to integrate ADHD into a custom agent framework is direct function invocation. This pattern works for any TypeScript or JavaScript orchestrator that can import NPM modules.

```typescript
import { run, renderText } from "adhd-agent";

async function brainstorm(problem: string) {
  const result = await run({
    problem,                // problem statement
    framesPerRun: 6,        // how many cognitive frames to use
    ideasPerFrame: 5,       // ideas generated per frame
    topK: 3,                // number of ideas to deepen
    codeMode: true,         // bias frames toward engineering topics
    concurrency: 4,         // parallel LLM calls
  });

  console.log(renderText(result)); // human-readable output
}

```

The `run` function internally performs the **reframe** phase (lines 31-46 in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)) to strip incidental anchors before entering the divergent thinking phases.

### Pattern 2: Custom Domain Frames

For domain-specific agents, you can override the default cognitive frames defined in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) by supplying custom frame definitions that match your industry or use case.

```typescript
import { run, renderText } from "adhd-agent";

// Define a bespoke frame for security auditing
const myFrames = [
  {
    id: "security-audit",
    label: "Security auditor",
    prompt: "Assess the solution from a security-audit perspective. List attack vectors and mitigations.",
    tags: ["design", "general"],
  },
  // Add additional domain-specific frames as needed
];

async function customBrainstorm(problem: string) {
  const result = await run({
    problem,
    framesPerRun: myFrames.length,
    // Override default frame selection
    // Note: The public API exposes selectFrames; custom frame arrays may require local patching
    frames: myFrames as any,
  });

  console.log(renderText(result));
}

```

The **`selectFrames`** helper in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) provides intelligent frame selection, but you can bypass it entirely by passing a custom `Frame[]` array to bias the divergent thinking toward specific perspectives.

### Pattern 3: Skill-Based Deployment

If your agent framework supports external skill definitions (such as Claude Code or custom skill loaders), you can integrate ADHD without writing boilerplate code. Place the [`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md) file in your agent's skill directory, then invoke via natural language commands:

```

/adhd "design a fault-tolerant cache layer"

```

The skill wrapper forwards requests to the same `run` implementation in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), preserving all architectural benefits including parallel divergent frames, critic scoring, and trap detection. This method requires no additional JavaScript code beyond the initial skill file installation.

### Pattern 4: Custom Orchestrator Wiring

For production agent orchestrators, you likely need to integrate ADHD into existing request-handling pipelines. This pattern demonstrates merging ADHD outputs into your agent's response flow:

```typescript
import { run } from "adhd-agent";

async function handleUserRequest(userPrompt: string) {
  // 1. Enrich prompt with context (e.g., repository code)
  const context = await fetchRelevantCode(userPrompt);

  // 2. Execute ADHD reasoning loop
  const adhdResult = await run({
    problem: userPrompt,
    context,
    ideasPerFrame: 8,
    topK: 4,
    concurrency: 6,
  });

  // 3. Merge ADHD output into your orchestrator's response structure
  const response = {
    summary: adhdResult.nonObviousPick?.text ?? "No clear pick",
    details: adhdResult.deepened.map(d => d.sketch).join("\n\n"),
    warnings: adhdResult.traps.map(t => `${t.text} – ${t.score?.trap}`).join("\n"),
  };

  return response;
}

```

This approach allows you to leverage ADHD's **nonObviousPick** for novel suggestions while surfacing **traps** as safety warnings in your agent's UI.

## Key Source Files Reference

Understanding these core files helps when debugging or extending your integration:

- **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)**: Core orchestration implementing the reframe → diverge → score → cluster → deepen pipeline
- **[`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts)**: Definition of the 15 built-in cognitive frames and the `selectFrames` picker utility
- **[`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)**: TypeScript interfaces for `RunOptions`, `RunResult`, `Frame`, and scoring structures
- **[`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts)**: Helper functions including `renderText` for human-readable output formatting
- **[`skills/adhd/SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md)**: Declarative skill definition for zero-code integration

## Summary

- **Install** the `adhd-agent` package via NPM or download the [`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md) file for skill-based integration.
- **Import** the `run` function from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) as your primary API entry point.
- **Configure** execution via `RunOptions`, tuning `framesPerRun`, `ideasPerFrame`, and `concurrency` for your latency requirements.
- **Customize** cognitive frames by modifying selections in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) or passing custom frame arrays for domain-specific thinking.
- **Process** the `RunResult` output to extract `nonObviousPick` for novel ideas, `deepened` for detailed sketches, and `traps` for risk mitigation.
- **Render** results using `renderText` from [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) or serialize the JSON for downstream processing in your agent pipeline.

## Frequently Asked Questions

### Can I use ADHD with Python-based agent frameworks?

No, the `adhd-agent` package is distributed as an NPM module for Node.js environments. To integrate ADHD into a custom agent framework built in Python, you would need to wrap the Node.js process using a subprocess call, expose the functionality via a REST API wrapper, or port the logic manually by reimplementing the `run` function from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) in Python.

### How does the `codeMode` parameter affect frame selection?

When `codeMode: true` is passed to `run`, the engine uses the `selectFrames` utility in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) to bias frame selection toward programming and software engineering perspectives. This filters the 15 built-in cognitive frames to prioritize those tagged with code-centric thinking patterns, resulting in suggestions more relevant to technical architecture and implementation challenges.

### What is the difference between `shortlist` and `nonObviousPick` in the results?

The **`shortlist`** array contains the top-ranked ideas based on critic scores across all frames, representing the most viable conventional solutions. The **`nonObviousPick`** is a specific field containing the single most novel viable suggestion that scored high on creativity metrics while remaining feasible, making it ideal when your agent framework needs unconventional or innovative recommendations rather than standard approaches.

### How do I handle high latency when running many frames concurrently?

Increase the **`concurrency`** parameter in your `RunOptions` configuration to allow more parallel LLM calls, though this is limited by your API rate limits. For severe latency constraints, reduce `framesPerRun` or `ideasPerFrame`, or implement a caching layer for the reframe phase (lines 31-46 in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)) since problem reframing is deterministic and safe to cache across similar queries.