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

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 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) 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:

npm install adhd-agent

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

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, while cognitive frames are defined in src/frames.ts and type declarations live in 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. 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) 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.

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) 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 by supplying custom frame definitions that match your industry or use case.

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 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 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, 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:

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: Core orchestration implementing the reframe → diverge → score → cluster → deepen pipeline
• src/frames.ts: Definition of the 15 built-in cognitive frames and the selectFrames picker utility
• src/types.ts: TypeScript interfaces for RunOptions, RunResult, Frame, and scoring structures
• src/render.ts: Helper functions including renderText for human-readable output formatting
• skills/adhd/SKILL.md: Declarative skill definition for zero-code integration

Summary

• Install the adhd-agent package via NPM or download the SKILL.md file for skill-based integration.
• Import the run function from 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 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 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 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 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) since problem reframing is deterministic and safe to cache across similar queries.

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