# How to Integrate ADHD into a Custom Agent Using the TypeScript Library API

> Learn to integrate ADHD into your custom TypeScript agent with the library API. Import run, configure options, and get a detailed reasoning tree for your agent.

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

---

**You can integrate ADHD into a custom TypeScript agent by importing the `run` function from the `adhd` package, configuring a `RunOptions` object with your problem statement and model selections, and awaiting the `Promise<RunResult>` that contains the full reasoning tree.**

The **ADHD** repository provides a TypeScript library that implements a tree-of-thought engine for generative agents. The core public API is exported from [`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts) and is designed to be model-agnostic, meaning you supply LLM names through `RunOptions` and the library handles inference via the internal `callLLM` helper in [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts). By importing just the `run` function and relevant types, you can embed a complete reframe-diverge-score-cluster-deepen cycle into any custom agent with full compile-time safety.

## Core Public API Exports

The entry point at [`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts) exposes a minimal, purpose-built surface:

- **`run`** – Executes the full reasoning cycle defined in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) and returns a `RunResult`.
- **`renderText`** – Converts a `RunResult` into a human-readable report; implemented in [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts).
- **`FRAMES` / `selectFrames`** – Built-in cognitive frames and a selection helper defined in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts).
- **Types (`Idea`, `RunOptions`, `RunResult`, …)** – All data structures live in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts).

Because the API is intentionally small, you only need `run` and the corresponding types to integrate ADHD into your own codebase.

## How the ADHD Engine Works

The reasoning cycle implemented in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) proceeds through four logical phases driven by system prompt constants such as `DIVERGE_SYSTEM`, `SCORE_SYSTEM`, and `DEEPEN_SYSTEM`:

1. **Reframe** – The `reframeProblem` function strips incidental anchors from the input problem statement.
2. **Diverge** – The `divergeBranch` function fires parallel cognitive frames (selected via `selectFrames`) and generates raw ideas per frame.
3. **Score and Cluster** – The `scoreIdeas` critic evaluates each idea, then `clusterIdeas` groups related concepts.
4. **Deepen** – The `deepenIdea` function expands the top-K ideas into concrete sketches and child ideas.

All LLM interactions are handled by `callLLM` in [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts), which forwards requests to the Claude Agent SDK. You control behavior entirely through the `RunOptions` interface without managing prompts manually.

## Integration Steps

Follow these steps to integrate ADHD into a custom TypeScript agent:

1. **Add the library** to your project with `npm install adhd` or a local path dependency.
2. **Construct a `RunOptions` object** that includes your `problem` string, optional `context`, and tuning parameters such as `framesPerRun`, `ideasPerFrame`, `topK`, `model`, and `criticModel`.
3. **Call `run(options)`** – The function returns a `Promise<RunResult>` containing the complete reasoning graph.
4. **Consume the result** – Use `renderText(result)` for CLI output, or process `result.shortlist`, `result.deepened`, and `result.clusters` programmatically in your agent pipeline.

## TypeScript Integration Examples

### Example 1: Simple One-Shot Invocation

This minimal example shows how to call the engine and inspect the shortlist and deepened ideas:

```typescript
import { run, type RunOptions } from "adhd";

async function demo() {
  const opts: RunOptions = {
    problem: "How can we automatically tag incoming support tickets?",
    context: "/* relevant TypeScript utilities */",
    framesPerRun: 4,
    ideasPerFrame: 5,
    topK: 2,
    model: "claude-3-sonnet-20240229",
    criticModel: "claude-3-opus-20240229",
  };

  const result = await run(opts);
  console.log("Shortlist:", result.shortlist.map(i => i.text));
  console.log("Deepened ideas:", result.deepened);
}

demo();

```

Key points:

- Only `run` and the `RunOptions` type are imported from the package entry point.
- The `RunResult` object contains the full reasoning graph, including the `shortlist` and `deepened` arrays.

### Example 2: Custom Agent Loop with Continuous Feedback

This pattern feeds the engine output back into the next iteration, using the generated provocation to evolve the agent's focus:

```typescript
import { run, type RunOptions, type RunResult } from "adhd";

async function iterativeAgent(initialProblem: string) {
  let problem = initialProblem;

  for (let iteration = 0; iteration < 3; ++iteration) {
    const opts: RunOptions = {
      problem,
      framesPerRun: 6,
      ideasPerFrame: 8,
      topK: 3,
      model: "claude-3-sonnet-20240229",
    };

    const result: RunResult = await run(opts);
    const bestSketch = result.deepened[0].sketch;

    console.log(`Iteration ${iteration + 1} – focus sketch:\n${bestSketch}`);

    problem = result.provocation;
  }
}

iterativeAgent("Create a zero‑downtime deployment pipeline");

```

Key points:

- The loop reuses the `problem` or the generated `provocation` to evolve focus across iterations.
- The `deepened` array provides concrete sketches that can be handed off to downstream tools such as code generators.

## Key Source Files and Architecture

Understanding the following files will help you debug and extend your integration:

- **[`src/index.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts)** – Public entry point that re-exports the main API.
- **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)** – Core engine containing `run`, `reframeProblem`, `divergeBranch`, `scoreIdeas`, `clusterIdeas`, and `deepenIdea`.
- **[`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)** – Type definitions for `Idea`, `RunOptions`, `RunResult`, and other data structures.
- **[`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts)** – Built-in cognitive frames and the `selectFrames` helper.
- **[`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts)** – Human-readable rendering logic for `RunResult`.
- **[`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts)** – Reference command-line wrapper demonstrating end-to-end library usage.
- **[`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts)** – Internal `callLLM` helper that routes requests to the Claude Agent SDK.

## Summary

- Import `run` and the required types from `"adhd"` to embed the engine with minimal boilerplate.
- Configure the cycle through the `RunOptions` interface, specifying your problem, models, and tuning parameters.
- The engine in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) executes a four-phase tree-of-thought cycle: **Reframe**, **Diverge**, **Score + Cluster**, and **Deepen**.
- Consume the structured `RunResult` programmatically or render it with `renderText` for human review.
- Because the library is model-agnostic at the configuration level, you can swap generator and critic models via `RunOptions` without changing integration code.

## Frequently Asked Questions

### What is the minimum API surface needed to integrate ADHD into an existing agent?

You only need to import `run` and the relevant types such as `RunOptions` and `RunResult` from the package entry point. The `run` function defined in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) encapsulates the entire reasoning cycle, so no additional classes or setup are required.

### Does ADHD require a specific LLM provider or SDK?

The engine is model-agnostic in terms of which Claude model you specify in `RunOptions`, but the internal `callLLM` helper in [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) forwards requests to the Claude Agent SDK. Therefore, you must have the Claude Agent SDK available in your project.

### How do I customize the cognitive frames used during the divergence phase?

You can import `FRAMES` and `selectFrames` from [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) to inspect or filter built-in frames, or you can adjust the `framesPerRun` parameter in your `RunOptions` to control how many frames fire per cycle.

### Can I override the system prompts that drive the reasoning phases?

Yes. The system prompts—such as `DIVERGE_SYSTEM`, `SCORE_SYSTEM`, and `DEEPEN_SYSTEM`—are kept as constants in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts). You can override them by patching the library source, or you can influence behavior by supplying different `model` and `criticModel` values in `RunOptions`.