Is There an API for UditAkhourii/adhd? Complete Guide to the ADHD Agent Library

Yes, the UditAkhourii/adhd repository exposes both a TypeScript library API and a CLI, centered around the run() function that orchestrates divergent thinking, idea scoring, and deepening through LLM calls.

The adhd project (also published as adhd-agent) is an open-source agentic framework designed to break creative blocks via structured brainstorming. According to the source code, the public API surface is intentionally minimal but powerful, allowing developers to embed full idea-generation pipelines directly into their own applications.

Core API Components

The library exports its public interface from [src/index.ts](https://github.com/UditAkhourii/adhd/blob/main/src/index.ts). The architecture consists of four primary components that handle the full lifecycle from problem statement to structured output.

The run() Method

The heart of the API is the run() function implemented in [src/engine.ts](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts). This async function executes a complete generation cycle:

1. Selects divergent frames (prompting strategies) to guide the LLM.
2. Generates raw ideas in parallel for each frame.
3. Runs a critic pass that scores each idea on novelty, viability, and fit, then clusters them.
4. Deepens the top-K ideas with implementation sketches, risk analysis, and child ideas.
5. Returns a fully typed RunResult object containing shortlist, nonObviousPick, traps, deepened, and clusters.

The renderText() Utility

Located in [src/render.ts](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts), the renderText() function converts a RunResult into a human-readable markdown string. This is the default formatter used by the CLI, but you can call it programmatically to display results in any UI.

Frame Selection Helpers

The [src/frames.ts](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) file exports:

• FRAMES: A static collection of prompt frames that define cognitive approaches (analogical, first-principles, constraint-focused, etc.).
• selectFrames(n): A utility that selects n random frames, with an option to disable engineering bias for more creative outputs.

Type Definitions

All public interfaces are centralized in [src/types.ts](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts). Key types include:

• RunOptions: Configuration for the brainstorming session (model, concurrency, frame count, idea count, LLM temperature).
• RunResult: The structured output containing scored ideas and deepened proposals.
• RunEvent: Used for progress callbacks during execution.
• Idea, Cluster, DeepenedIdea: Data structures for the generated content.

How to Use the ADHD API

The ADHD agent can be invoked via command line for quick tasks or imported as a library for embedded workflows.

CLI Usage

The CLI is a thin wrapper around the library. Most flags map 1-to-1 to RunOptions properties:

# Basic usage

adhd "design a rate limiter that survives leader election"

# Fine-tuned execution with specific parameters

adhd "refactor this module" --frames 3 --ideas 8 --top 2 --model anthropic

The CLI reads optional context from stdin or files and streams JSON output when invoked with --json.

Programmatic TypeScript Usage

Import the core functions to embed the agent in your application:

import { run, renderText, FRAMES } from "adhd-agent";
import { readFileSync } from "fs";

async function brainstormArchitecture() {
  // Load relevant code or documentation as context
  const context = readFileSync("./src/queue.ts", "utf8");

  // Execute the full pipeline
  const result = await run({
    problem: "How should we shard this queue under bursty load?",
    context: context,
    framesPerRun: 6,
    ideasPerFrame: 8,
    topK: 3,
    concurrency: 4,
    onEvent: (e) => console.error(`Event: ${e.type}`), // Progress tracking
  });

  // Human-readable markdown output
  console.log(renderText(result));

  // Structured data for downstream processing
  console.log("Best ideas:", result.shortlist);
  console.log("Hidden gem:", result.nonObviousPick);
  console.log("Warnings:", result.traps);
  console.log("Deep analysis:", result.deepened);
}

brainstormArchitecture();

Embedding in AI Workflows

You can use run() as a sub-agent within larger autonomous systems:

// Inside a planning loop
if (needsCreativeExploration) {
  const { deepened, shortlist } = await run({
    problem: currentDecision,
    context: relevantCodeContext,
    framesPerRun: 4,
    topK: 2,
    codeMode: true, // Optimizes prompts for technical solutions
  });

  // Feed deepened sketches into your main agent
  await mainAgent.evaluateProposals(deepened);
}

Integration Architecture

The API uses Zod schemas internally for validation, ensuring that LLM outputs conform to the expected RunResult shape. The parallel execution model (controlled by the --concurrency flag) respects rate limits while maximizing throughput across multiple frames.

When using the library programmatically, you have full control over:

• Frame selection: Use selectFrames() for random diversity or specify exact frames via options.frames.
• Scoring criteria: The built-in critic evaluates ideas on multiple dimensions before clustering.
• Deepening depth: The topK parameter determines how many ideas receive full expansion treatment.

Summary

• UditAkhourii/adhd provides a dual-interface API: CLI for command-line usage and TypeScript library for programmatic integration.
• The run() function in [src/engine.ts](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) is the primary entry point, handling the complete ideation pipeline from framing to deepening.
• Helper utilities like renderText() and selectFrames() allow fine-grained control over output formatting and cognitive approaches.
• All types are fully defined in [src/types.ts](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts), enabling complete type safety for consumers.
• The architecture supports both standalone execution and embedding within larger agent workflows via the onEvent callback system.

Frequently Asked Questions

How do I install the ADHD API?

Install the package via npm to access both the CLI and library: npm install -g adhd-agent for global CLI access, or npm install adhd-agent as a project dependency. The package exports all public types and the run function from its main entry point.

What is the difference between the CLI and the library API?

The CLI is a thin wrapper that parses command-line arguments, reads files/stdin, and calls the underlying run() function. The library API gives you direct access to the same run() method with full TypeScript support, allowing you to customize RunOptions, handle events programmatically, and process the RunResult object without shelling out to a subprocess.

Can I use the ADHD API without TypeScript?

Yes, the package is compiled to JavaScript and can be used in plain Node.js environments. While the source is written in TypeScript (with type definitions in [src/types.ts](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)), CommonJS and ESM builds are provided for vanilla JavaScript consumption.

Does the API support custom LLM providers?

The current implementation supports configurable model selection through the model option in RunOptions, which maps to the CLI's --model flag. The engine is designed to work with standard LLM APIs (OpenAI, Anthropic) through environment variables like OPENAI_API_KEY or ANTHROPIC_API_KEY, as documented in [documentation/api.md](https://github.com/UditAkhourii/adhd/blob/main/documentation/api.md).

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