# How to Integrate UditAkhourii/adhd with Other Tools: Three Methods for the Ideation Engine

> Learn three ways to integrate UditAkhourii/adhd with your workflow: NPM library, CLI, or Claude-compatible agent skills. Unlock its ideation engine easily.

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

---

**You can integrate the adhd parallel divergent ideation engine via NPM library imports, CLI execution, or Claude-compatible agent skills, exposing the core `run` function from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) to any Node.js or shell environment.**

The **UditAkhourii/adhd** repository implements a cognitive ideation system that generates multiple solution frames simultaneously using LLM-powered divergence and clustering. Because the architecture isolates core logic in a pure TypeScript function rather than a monolithic application, you can embed this capability into editors, CI pipelines, or agent frameworks. This guide covers the three integration methods supported by the codebase: programmatic library calls, command-line invocation, and skill-based agent integration.

## Architecture Overview

The repository organizes functionality into three distinct layers to maximize reusability:

- **CLI / Skill entry point** ([`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts)): Parses user arguments, validates options, and formats output for terminal or JSON consumption.
- **Engine** ([`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)): Orchestrates the *diverge → score/cluster → deepen* loop, managing frame selection, concurrency, and optional anchor stripping.
- **Support modules**: [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) defines cognitive frames, [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) provides TypeScript interfaces for ideas and results, [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) wraps the Claude Agent SDK, and [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) handles human-readable formatting.

This separation allows external tools to hook into any layer, from low-level engine calls to high-level CLI execution.

## Integration Methods

### Programmatic Integration via NPM Library

Import the `adhd-agent` package to embed ideation directly into Node.js applications. The main entry point is the `run` function exported from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), which accepts a `RunOptions` object and returns a `RunResult` promise.

Key parameters include:

- `problem`: The design challenge or coding task to solve.
- `context`: Optional code snippets or system constraints.
- `framesPerRun`: Number of cognitive frames to generate.
- `ideasPerFrame`: Solutions generated per frame.
- `model`: LLM identifier for generation (e.g., `claude-3-5-sonnet-20240620`).
- `criticModel`: Separate LLM for scoring and clustering (e.g., `claude-3-opus-20240229`).

```typescript
// demo.ts
import { run } from "adhd-agent";

async function generateDesign() {
  const result = await run({
    problem: "Design a low-latency, fault-tolerant queue",
    context: "// Node.js, Redis-based, 10k RPS",
    framesPerRun: 6,
    ideasPerFrame: 8,
    topK: 3,
    model: "claude-3-5-sonnet-20240620",
    criticModel: "claude-3-opus-20240229",
  });

  console.log(result.shortlist.map(i => i.text));
}

```

This method suits VS Code extensions, custom LLM orchestrators, and CI pipelines that need to generate design proposals programmatically.

### Shell Integration via CLI

For bash scripts, GitHub Actions, or ad-hoc terminal usage, install the `adhd-agent` package globally or run via `npx` to access the `adhd` command defined in [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts).

The CLI accepts positional arguments for the problem statement and flags for configuration:

- `--frames`: Number of frames to generate.
- `--ideas`: Ideas per frame.
- `--top`: Number of top results to return.
- `--model` and `--critic-model`: LLM specifications.
- `--json`: Output raw JSON for piping to tools like `jq`.

```bash
#!/usr/bin/env bash

# run-adhd.sh

PROBLEM="Add rate-limiting to API gateway"
adhd "$PROBLEM" \
  --frames 5 \
  --ideas 7 \
  --top 2 \
  --model claude-3-5-sonnet-20240620 \
  --critic-model claude-3-opus-20240229 \
  --json > result.json

jq '.shortlist[] | .text' result.json

```

The CLI handles parsing via [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts), invokes the engine, and renders results through [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) or JSON serialization.

### Agent Integration via Claude-Compatible Skills

The repository includes a YAML skill definition at [`skills/adhd/SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md) that registers an `/adhd` command within Claude-compatible agents like **Claude Code**, **Cursor**, or **Codex**.

Install the skill using the skills CLI:

```bash
npx skills add UditAkhourii/adhd

```

Once registered, agents can trigger the engine directly from chat:

```

/adhd "How can we make the build faster on CI?"

```

The skill forwards the prompt to the same `run` function used in programmatic integration, with results formatted through [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts).

## Customization and Extension Points

The engine exposes several extension mechanisms for domain-specific workflows:

**Custom Frames**: Modify the `FRAMES` array in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) to add new cognitive perspectives or domain-specific lenses, then rebuild the package.

**Model Selection**: Pass distinct `model` and `criticModel` values to use different LLM families for generation versus evaluation, optimizing cost and accuracy.

**Anchor Stripping**: Control context contamination by setting `stripAnchors` (default `true`) in `RunOptions` or using `--no-anchor-strip` in CLI. This removes incidental references (like current stack traces) before divergence, improving independence across frames as implemented in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) lines 31-41.

## Summary

- **Library Import**: Import `run` from `adhd-agent` to embed ideation in Node.js applications, passing custom `RunOptions` to control frames, models, and output.
- **CLI Execution**: Use the `adhd` command with `--json` flags for shell scripts and automation pipelines that require machine-readable output.
- **Agent Skills**: Install via `npx skills add UditAkhourii/adhd` to enable `/adhd` commands in Claude Code, Cursor, or Codex.
- **Customization**: Extend frames in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts), configure separate models for generation and criticism, and toggle anchor stripping via options or CLI flags.

## Frequently Asked Questions

### Can I integrate the adhd engine without installing it as a global package?

Yes. Use `npx adhd-agent` to run the CLI without installation, or import the package as a local dependency in your [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json). The engine requires only Node.js and does not depend on global system packages or specific environment configurations.

### How do I customize the cognitive frames used during ideation?

Edit the `FRAMES` array in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) to add, remove, or modify cognitive perspectives, then rebuild the package. Each frame represents a distinct lens (e.g., "security", "performance") through which the LLM evaluates the problem, allowing domain-specific customization of the divergence strategy.

### What is the difference between the `model` and `criticModel` parameters?

The `model` parameter specifies the LLM used for generating initial ideas across frames, while `criticModel` designates a potentially different LLM for scoring, clustering, and selecting the top-K results. This separation allows you to use faster, cheaper models for generation and more powerful models for evaluation, optimizing both cost and quality as defined in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) and implemented in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts).

### Is the CLI output machine-readable for automation pipelines?

Yes. Pass the `--json` flag to the `adhd` command to receive structured JSON output containing the full `RunResult` object, including the `shortlist` array of top ideas. This integrates cleanly with `jq`, GitHub Actions, or any tool that parses JSON streams, as handled by the output logic in [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts).