# UditAkhourii/adhd Usage Examples: CLI, Agent, and Library Integration

> Explore UditAkhourii/adhd usage examples including CLI, agent skills, and library integration. Discover its two-phase reasoning engine for divergent ideation.

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

---

**The UditAkhourii/adhd repository exposes a two-phase reasoning engine for parallel divergent ideation through three primary interfaces: a global CLI, an agent skill command, and a programmatic TypeScript API.**

The UditAkhourii/adhd project structures creative problem-solving into distinct divergence and focus phases. Developers can invoke the engine via terminal commands, integrate it into agent workflows, or import functions directly from the `adhd-agent` package. All usage patterns rely on core orchestration logic in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) and frame selection utilities in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts).

## CLI Usage and Installation

The fastest way to experiment with UditAkhourii/adhd is through the global command-line interface. Install the package and run divergent ideation sessions directly from your terminal.

### Installing the Global CLI

Install `adhd-agent` globally via npm to access the `adhd` command:

```bash
npm install -g adhd-agent

```

### Running Basic and Customized Sessions

Invoke the engine with a problem statement. The CLI automatically handles reframing, frame selection, and idea generation according to the implementation in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts):

```bash

# Basic prompt

adhd "design a rate limiter that survives a leader election"

# Custom breadth and depth

adhd "name this feature-flag service" --frames 3 --ideas 8 --top 2

```

These commands trigger the full workflow: `reframeProblem` strips incidental anchors using the `REFRAME_SYSTEM` prompt, `selectFrames` chooses N cognitive frames (default 5), and each frame spawns isolated LLM calls under the `DIVERGE_SYSTEM` prompt to produce JSON arrays validated against `DivergeRowSchema`.

## Agent Skill Integration

For AI agent environments, UditAkhourii/adhd ships as a runnable skill that exposes the `/adhd` slash command. Install the skill using the skills CLI:

```bash
npx skills add UditAkhourii/adhd

```

Once installed, agents can invoke the divergent ideation engine inline:

```bash

# Then in the agent console

/adhd "design a retry strategy for an LLM request that sometimes hangs"

```

This interface leverages the same `run` function defined in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), returning structured results through the agent's messaging interface.

## TypeScript Library API

For programmatic control, import the engine directly into Node.js or TypeScript projects. The library exposes granular functions for full execution and frame management.

### Running the Full Ideation Engine

Import `run` and `renderText` from `adhd-agent` to execute the complete six-phase workflow:

```ts
import { run, renderText } from "adhd-agent";

const result = await run({
  problem: "How should we shard this queue under bursty load?",
  topK: 3,
  framesPerRun: 5,
  ideasPerFrame: 6,
});

console.log(renderText(result));
// Output contains: shortlist, nonObviousPick, traps, deepened ideas, provocation

```

According to the source code in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), the `run` function orchestrates: optional reframing via `reframeProblem`, divergence via `divergeBranch` across selected frames, scoring via `scoreIdeas` (parsing `ScoreRowSchema`), clustering via `clusterIdeas`, shortlisting to remove traps, and deepening via `deepenIdea`. The result object conforms to the `DeepenSchema` and related type definitions in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts).

### Direct Frame Selection

Access the frame selection logic directly via `selectFrames` in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) to inspect which cognitive frames will participate in divergence:

```ts
import { selectFrames } from "adhd-agent/src/frames";

const frames = selectFrames(5, true); // 5 code-oriented frames
console.log(frames.map(f => f.label));

```

This function returns frame objects that drive the `divergeBranch` calls, each operating under isolated system prompts to ensure diverse idea generation across the 15 available cognitive frames.

## Core Implementation Details

Understanding the file structure helps when customizing usage of UditAkhourii/adhd.

### Engine Orchestration ([`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts))

The main entry point `run` coordinates the entire pipeline. Key functions include:

- **`reframeProblem`**: Strips incidental anchors using the `REFRAME_SYSTEM` prompt before frame distribution
- **`scoreIdeas`**: Parses `ScoreRowSchema` JSON to calculate weighted totals across novelty, viability, and fit dimensions
- **`clusterIdeas`**: Groups ideas by underlying angle using the `CLUSTER_SYSTEM` prompt
- **`deepenIdea`**: Expands shortlisted ideas into sketches, risks, first steps, and child ideas following `DeepenSchema`

### Frame Management ([`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts))

The `selectFrames` function chooses from 15 predefined cognitive frames. Each frame triggers an isolated LLM call via `divergeBranch`, producing ideas validated against `DivergeRowSchema`.

### Type Safety ([`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts))

All JSON outputs are strictly typed. Key interfaces include `DivergeRowSchema` for raw ideas, `ScoreRowSchema` for critic evaluations, and `DeepenSchema` for expanded concept development.

## Summary

- **UditAkhourii/adhd** exposes parallel divergent ideation through CLI, agent skills, and TypeScript APIs
- Install globally via `npm install -g adhd-agent` for terminal usage with customizable `--frames` and `--ideas` flags
- Add to agents via `npx skills add UditAkhourii/adhd` to enable the `/adhd` slash command
- Import `run` and `selectFrames` from `adhd-agent` for programmatic control over the six-phase engine
- Core logic resides in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) (orchestration) and [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) (cognitive frame selection)
- All data structures are typed in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) using Zod schemas including `DivergeRowSchema`, `ScoreRowSchema`, and `DeepenSchema`

## Frequently Asked Questions

### How do I customize the number of frames and ideas in UditAkhourii/adhd?

Use the `--frames` and `--ideas` flags when running the CLI, or pass `framesPerRun` and `ideasPerFrame` to the `run` function in the TypeScript API. The default configuration selects 5 frames with 6 ideas per frame, as defined in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts).

### What determines the "non-obvious pick" in the output?

The engine scores all generated ideas using `scoreIdeas` against dimensions like novelty, viability, and fit. After filtering out traps, the highest-novelty viable idea becomes the non-obvious pick. This logic is implemented in the shortlisting phase of [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts).

### Can I use UditAkhourii/adhd without installing it globally?

Yes. You can use `npx adhd-agent` for one-off CLI executions, integrate it as an agent skill without global installation, or import specific functions like `selectFrames` from `adhd-agent/src/frames` in your TypeScript projects.

### Where are the system prompts defined for the divergence and scoring phases?

System prompts including `DIVERGE_SYSTEM`, `REFRAME_SYSTEM`, and `CLUSTER_SYSTEM` are imported and used within [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) and [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts). These prompts define the cognitive constraints for each phase of the ideation process, though they are typically internal to the package and invoked automatically by the `run` function.