# What Is the Learning Curve for UditAkhourii/adhd? A Technical Breakdown

> Discover the shallow learning curve of UditAkhourii/adhd. Generate ideas in minutes with the CLI or API and customize with its modular architecture.

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

---

**The UditAkhourii/adhd library features a deliberately shallow learning curve that enables users to generate divergent ideas within five minutes via CLI or TypeScript API, while its modular architecture supports deep customization with only moderate additional effort.**

The **UditAkhourii/adhd** repository implements a "Parallel Divergent Ideation" engine for AI-assisted creative problem solving. Understanding the **learning curve for UditAkhourii/adhd** helps developers determine whether this reasoning tool fits their workflow, from quick command-line prototyping to advanced algorithmic extension. The codebase balances immediate accessibility with architectural depth, separating concerns across distinct modules that allow progressive disclosure of complexity.

## Entry Points and Initial Setup

The repository ships three first-class entry points that minimize initial friction: a **CLI**, a **TypeScript library**, and a **Claude-Code skill**. According to the source code analysis, the documentation at [`documentation/quickstart.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/quickstart.md) guides new users through each path using minimal shell commands.

Zero-configuration installation options include:

- `npm install -g adhd-agent` for global CLI access
- `npx skills add UditAkhourii/adhd` for Claude-Code integration

These one-line setups allow immediate execution of the engine without configuration files or environment setup. The initial barrier to entry remains under five minutes, making the **learning curve for UditAkhourii/adhd** nearly flat for basic usage.

## Core Data Model and Types

All fundamental concepts reside in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts), a small type-only file that defines **Idea**, **Score**, **RunResult`, and other interfaces. This centralized type system maps one-to-one with the JSON outputs returned by the engine.

Because the data structures are straightforward and self-documenting, understanding the output shape requires reviewing only this single file. Users can write custom consumers for the engine's results without traversing the entire codebase, significantly flattening the intermediate learning curve.

## The Two-Phase Engine Architecture

The core algorithm lives in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), specifically within the well-commented `run` function. This implementation separates **divergence** (parallel generation under distinct "frames") from **convergence** (scoring, clustering, and deepening).

The flow mirrors the README's high-level diagram, creating a direct mapping between documentation and implementation. Reading the comment block at the top of [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) provides sufficient understanding of the entire algorithm, allowing users to grasp the two-phase loop without deep code archaeology.

## Customization Without Complexity

The **ADHD** library exposes extension points that allow domain-specific customization without core algorithm modifications.

**Extensible Frames** are implemented in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts), shipping with 15 default cognitive lenses. Adding a new frame requires only appending a JSON object containing an `id`, `label`, and `prompt` to the frames array. This architecture enables users to steer divergent ideation toward specific domains without touching the engine logic.

**Decoupled Rendering** in [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) converts `RunResult` instances into color-coded terminal output. Because the renderer is separate from the engine, users can invoke `--json` mode to bypass rendering entirely and work directly with raw JSON outputs, reducing friction for programmatic integrations.

## Practical Code Examples

### Command-Line Usage

```bash

# Install the CLI globally (once)

npm install -g adhd-agent

# Generate ideas for a design problem

adhd "design a rate limiter that survives a leader election" \
     --frames 6 --ideas 8 --top 2

```

The CLI, implemented in [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts), parses flags, validates inputs, and forwards them to the engine while printing human-readable progress events.

### Programmatic TypeScript Integration

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

async function demo() {
  const result = await run({
    problem: "How should we shard this queue under bursty load?",
    framesPerRun: 5,   // number of divergent frames
    ideasPerFrame: 6,  // ideas per frame
    topK: 3,           // how many to deepen
  });

  console.log(renderText(result)); // human-readable output
  // Or work with the raw JSON:
  // console.log(result.shortlist);
}

demo();

```

The `run` function returns a `RunResult` containing all intermediate data including branches, scores, and clusters.

### Adding Custom Frames

```typescript
import { run } from "adhd-agent";

// Define a new frame
const customFrame = {
  id: "security-first",
  label: "Security-first perspective",
  prompt: "Consider security implications first."
};

// Use custom frames in execution
const result = await run({
  problem: "Expose a public API for user data",
  framesPerRun: 1,
  ideasPerFrame: 5,
  // Injection mechanism varies by version; consult src/engine.ts for exact API
});

```

## Summary

- **Initial ramp-up** takes less than five minutes using the CLI or library import with zero configuration required.
- **Intermediate mastery** of the two-phase loop and custom frame addition requires approximately 30 minutes of reading [`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).
- **Advanced extension** involving scoring system modifications or LLM integration requires 1-2 hours of exploration, bounded by the modular separation of `engine`, `cli`, `render`, and `frames` modules.
- **Type safety** is centralized in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts), eliminating the need to hunt through multiple files to understand data structures.
- **Documentation** includes API references, usage guides, and comparative analysis, providing clear learning paths without forcing code exploration.

## Frequently Asked Questions

### How long does it take to become productive with UditAkhourii/adhd?

Most users can generate their first divergent ideation results within five minutes of installation. The CLI and library APIs mirror each other exactly, so skills transfer immediately between command-line and programmatic usage. Deep customization of frames requires an additional 30 minutes of documentation review.

### Can I use the library effectively without reading the core engine code?

Yes. The **ADHD** library's public `run` function in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) exposes a clean interface that abstracts the two-phase divergence-convergence algorithm. Users working with the CLI or basic TypeScript imports never need to examine internal scoring or clustering logic unless extending the system.

### What specific files determine the learning curve difficulty?

Four files govern the complexity gradient: [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) defines data structures (minimal learning curve), [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) enables customization (moderate curve), [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) contains the core algorithm (steeper curve for contributors), and [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) provides entry-level tooling (minimal curve). The optional test file at [`tests/llm.test.ts`](https://github.com/UditAkhourii/adhd/blob/main/tests/llm.test.ts) offers additional insight for advanced users but is not required for basic usage.

### Is it difficult to add custom reasoning frames to the engine?

Adding custom frames is straightforward and requires no changes to the core algorithm. Users define a JSON object with `id`, `label`, and `prompt` properties, then inject these into the frames array. The modular design of [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts) keeps this customization accessible to intermediate users while maintaining the engine's integrity.