# ADHD NPM Library vs CLI vs Skill Installation: What's the Difference?

> Explore the differences between the ADHD NPM library, CLI, and skill installation methods. Understand how each approach interacts with the core ADHD engine for diverse usage.

- Repository: [Udit Akhouri/adhd](https://github.com/UditAkhourii/adhd)
- Tags: comparison
- Published: 2026-08-01

---

**The ADHD project offers three distinct consumption methods—NPM CLI, Skill installation, and programmatic SDK—all invoking the same core engine from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) but differing in entry points, distribution mechanisms, and runtime environments.**

The [UditAkhourii/adhd](https://github.com/UditAkhourii/adhd) repository provides multiple installation pathways to accommodate terminal users, chat-based agent workflows, and direct library imports. Whether you need a command-line brainstorming tool, a Claude Code skill, or a TypeScript module for your application, understanding these **ADHD npm library CLI skill installation methods** ensures you choose the right integration strategy. Each approach ultimately calls the identical `run` function defined in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), guaranteeing consistent output quality across all consumption modes.

## Three Ways to Install and Run ADHD

### NPM CLI Installation (Global or Local)

Install the **adhd-agent** package via NPM to access both the binary and the underlying library. Global installation provides the `adhd` command system-wide, while local installation adds it as a project dependency.

```bash

# Global installation for terminal access anywhere

npm install -g adhd-agent

# Local installation for project-specific use

npm install adhd-agent

```

Once installed, invoke the tool directly from your shell using the `adhd` binary defined in [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json). The CLI entry point at [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) parses arguments, constructs a `RunOptions` object, and executes the engine.

### Skill Installation via Skills CLI

For users of Claude Code, Cursor, or other supported agents, install ADHD as a **skill** using the Skills CLI. This method requires no NPM package manager interaction within the host environment.

```bash
npx skills add UditAkhourii/adhd

```

This command copies the [`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md) file from `skills/adhd/` into your agent's skill folder. The skill definition contains YAML front-matter that registers the `/adhd` command with the agent, pointing to the same engine code used by the CLI.

### Programmatic SDK Integration

Import the library directly into TypeScript or JavaScript applications for custom integrations. This method provides the most flexibility for embedding ADHD's ideation engine into existing workflows.

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

const result = await run({
  problem: "design a rate limiter that survives a leader election",
  framesPerRun: 5,
  topK: 3,
});

```

## Architectural Differences Between Installation Methods

### Entry Points and Invocation

**CLI Method**: Execution begins at [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts), which handles flag parsing (e.g., `--json` for machine-readable output), builds the options object, calls `run(opts)`, and formats results using `renderText` from [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts).

**Skill Method**: The entry point is the [`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md) file, a declarative document containing metadata that instructs the host agent how to invoke the `run` function. The agent's runtime imports the library behind the scenes, making the skill essentially a thin wrapper around the engine.

### Distribution and Packaging

**NPM Distribution**: Delivered through the Node package registry as the `adhd-agent` package. This includes the compiled binary, TypeScript definitions, and all dependencies required for standalone execution.

**Skill Distribution**: Distributed as a plain markdown file within the repository's `skills/adhd/` directory. The Skills CLI copies this file into the agent's configuration, eliminating the need for traditional package management within the agent environment.

### Runtime Environment and Authentication

**CLI Runtime**: Executes within a standalone Node.js process that reads the `ANTHROPIC_API_KEY` environment variable directly from your shell or inherits it from a local Claude Code installation.

**Skill Runtime**: Executes inside the host agent's process. The agent supplies authentication credentials (such as stored API keys from the Claude Code UI) and may apply additional context handling or sandboxing specific to that agent.

### Ideal Use Cases

- **NPM CLI**: Best for scripting, CI/CD pipelines, and quick terminal-based brainstorming sessions where you need formatted text or JSON output.
- **Skill Installation**: Optimized for interactive chat workflows where you want to invoke `/adhd` alongside other agent capabilities, allowing the skill to auto-trigger during ideation or naming tasks.
- **Programmatic SDK**: Ideal for building custom applications, automated testing frameworks, or integrations requiring fine-grained control over the `RunOptions` parameters.

## Code Examples for Each Method

### Using the NPM-Installed CLI

```bash

# Simple text output for human reading

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

# JSON output for downstream processing

adhd "design a rate limiter" --json > result.json

```

Behind the scenes, [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) processes these flags and calls `renderText` or outputs raw JSON based on your selection.

### Adding the Skill to an Agent

```bash

# One-time installation via Skills CLI

npx skills add UditAkhourii/adhd

```

After restarting your agent, invoke the skill naturally:

```

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

```

The agent parses [`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md) and routes the command to the ADHD engine automatically.

### Programmatic Usage in TypeScript

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

async function generateIdeas() {
  const result = await run({
    problem: "optimize database queries for high-traffic events",
    framesPerRun: 5,
    topK: 3,
  });
  
  return result.clusters; // Access structured data directly
}

```

## Key Source Files and Their Roles

Understanding the repository structure clarifies how these methods converge on the same core logic:

- **[`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts)**: CLI entry point handling argument parsing, environment setup, and result formatting via `renderText`.
- **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)**: Core engine containing the `run` function that fans out frames, scores ideas, clusters results, and performs deep analysis.
- **[`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts)**: Human-readable text formatter used exclusively by the CLI for terminal output.
- **[`skills/adhd/SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md)**: Declarative skill definition registering the `/adhd` command with agent systems.
- **[`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json)**: Defines the `adhd-agent` package metadata and maps the `adhd` binary to the compiled CLI entry point.

## Summary

- **Three installation methods** serve different workflows: NPM CLI for terminals, Skills CLI for agents, and direct import for applications.
- **Unified engine**: All methods ultimately execute the `run` function from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), ensuring identical ideation quality.
- **Different entry points**: [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) handles shell interactions while [`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md) enables agent integration.
- **Flexible authentication**: CLI uses environment variables; skills inherit credentials from the host agent.
- **Consistent outputs**: Whether using `adhd "query"` or `/adhd "query"`, the underlying clustering and scoring logic remains the same.

## Frequently Asked Questions

### Can I use the ADHD skill without installing the NPM package?

Yes. The skill installation via `npx skills add` copies only the [`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md) file to your agent's skill folder. The host agent (Claude Code, Cursor, etc.) handles the library import internally, so you do not need to run `npm install` yourself. However, the agent must have network access or a cached version of the `adhd-agent` package to execute the skill.

### Does the skill installation provide different output than the CLI?

No. Both the skill and the CLI invoke the same `run` function from [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts). The output differences are limited to formatting: the CLI uses `renderText` from [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) for terminal display, while skills may present results through the agent's native UI. The underlying ideas, clusters, and scores are identical.

### Which installation method is best for CI/CD pipelines?

Use the **NPM CLI method** for CI/CD environments. Install `adhd-agent` globally or as a dev dependency, then invoke `adhd "your problem" --json` to capture structured output. This approach provides deterministic behavior, explicit version pinning through [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json), and direct control over the `ANTHROPIC_API_KEY` environment variable.

### How do I customize engine parameters when using the skill?

Skill users typically interact through the `/adhd` command with default parameters defined in [`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md). For custom `framesPerRun` or `topK` values, use the **programmatic SDK** method instead. Import `run` from `adhd-agent` and pass a complete `RunOptions` object to configure the engine's ideation frames, clustering thresholds, and depth parameters.