> ## Documentation Index
> Fetch the complete documentation index at: https://adhd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Library Reference

> The adhd-agent TypeScript API — run options, the structured result, and exports.

```bash theme={null}
npm install adhd-agent
```

Requires Node.js 18+. Auth comes from `ANTHROPIC_API_KEY` or a local Claude Code install.

## Exports

```ts theme={null}
import { run, renderText, FRAMES, selectFrames } from "adhd-agent";
import type {
  RunOptions, RunResult, Idea, Branch, Cluster,
  DeepenedIdea, Score, RunEvent,
} from "adhd-agent";
```

## `RunOptions`

```ts theme={null}
type RunOptions = {
  problem: string;
  context?: string;
  framesPerRun?: number;   // default 5
  ideasPerFrame?: number;  // default 6
  topK?: number;           // default 3
  concurrency?: number;    // default 4
  codeMode?: boolean;      // default true — bias frames toward engineering
  stripAnchors?: boolean;  // strip incidental anchors before fan-out, default true
  model?: string;          // generator + critic
  criticModel?: string;    // critic (score + cluster) only; defaults to `model`
  onEvent?: (e: RunEvent) => void;
};
```

## A full run

```ts theme={null}
import { run, renderText } from "adhd-agent";
import { readFileSync } from "node:fs";

const result = await run({
  problem: "How should we shard this queue under bursty load?",
  context: readFileSync("./queue.ts", "utf8"),
  framesPerRun: 6,
  ideasPerFrame: 8,
  topK: 3,
  onEvent: (e) => console.error(e),
});

console.log(renderText(result));
```

## The result

Everything in `RunResult` is structured — clusters, scored ideas with `novelty / viability / fit`, trap reasons, deepened sketches with child ideas. Route it into your own renderer, downstream agent, or planning loop.

| Field                   | What it holds                                                                   |
| ----------------------- | ------------------------------------------------------------------------------- |
| `result.shortlist`      | the 2–4 most promising ideas, with scores                                       |
| `result.nonObviousPick` | the highest-novelty **viable** idea, even if not the highest-fit                |
| `result.traps`          | the "looks good but isn't" list, each with a mechanistic reason                 |
| `result.deepened`       | the top-K ideas expanded: sketch + load-bearing risk + first step + child ideas |
| `result.clusters`       | the *shape* of the idea space, grouped by underlying angle                      |

For calling `run()` at decision points inside a larger agent, see [Agent integration](/usage/agent-integration).