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

> Explore the UditAkhourii/adhd repository's API. This guide details the ADHD Agent Library, focusing on the run() function for divergent thinking, idea scoring, and LLM integration. Access insights via TypeScript or CLI.

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

---

**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)](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)](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)](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)](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)](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:

```bash

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

```typescript
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:

```typescript
// 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)](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)](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)](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)](https://github.com/UditAkhourii/adhd/blob/main/documentation/api.md).