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

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 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. 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 exposes a minimal, purpose-built surface:

• run – Executes the full reasoning cycle defined in src/engine.ts and returns a RunResult.
• renderText – Converts a RunResult into a human-readable report; implemented in src/render.ts.
• FRAMES / selectFrames – Built-in cognitive frames and a selection helper defined in src/frames.ts.
• Types (Idea, RunOptions, RunResult, …) – All data structures live in 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 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, 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:

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:

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 – Public entry point that re-exports the main API.
• src/engine.ts – Core engine containing run, reframeProblem, divergeBranch, scoreIdeas, clusterIdeas, and deepenIdea.
• src/types.ts – Type definitions for Idea, RunOptions, RunResult, and other data structures.
• src/frames.ts – Built-in cognitive frames and the selectFrames helper.
• src/render.ts – Human-readable rendering logic for RunResult.
• src/cli.ts – Reference command-line wrapper demonstrating end-to-end library usage.
• 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 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 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 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 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. You can override them by patching the library source, or you can influence behavior by supplying different model and criticModel values in RunOptions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}