# Requirements for Setting Up and Running the ADHD Skill: Complete Guide

> Discover the essential requirements for setting up and running the ADHD skill. Learn about Node.js 18+, API keys, and deployment options as an agent, CLI, or library.

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

---

**TL;DR:** The ADHD skill requires Node.js 18+, an `ANTHROPIC_API_KEY` environment variable, and can be deployed as an agent skill, CLI tool, or TypeScript library.

The **ADHD (Accelerated Divergent Heuristic Deepening)** skill implements a two-phase divergent-then-convergent reasoning loop powered by Anthropic's Claude model. According to the [UditAkhourii/adhd](https://github.com/UditAkhourii/adhd) source code, setup requirements vary slightly depending on whether you run it as an agent skill, standalone CLI, or embedded library. This guide covers all prerequisites and installation paths with exact commands.

## Core Requirements for the ADHD Skill

All three deployment modes share these foundational dependencies:

| Requirement | Purpose | Source Location |
|-------------|---------|---------------|
| **Node.js ≥ 18** | Runtime for compiled TypeScript and CLI binary | [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json) [`engine` field](https://github.com/UditAkhourii/adhd/blob/main/package.json#L56-L57) |
| **`ANTHROPIC_API_KEY`** | Authenticates Claude API calls via the Claude Agent SDK | [`documentation/install.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md) [Auth section](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md#L95) |
| **Core dependencies** | Runtime libraries: `@anthropic-ai/claude-agent-sdk`, `p-limit`, `zod` | [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json) [`dependencies`](https://github.com/UditAkhourii/adhd/blob/main/package.json#L58-L62) |
| **Internet access** | Required for `npx skills add` and API calls | [`documentation/install.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md) [One-command install](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md#L7-L15) |
| **Git** (optional) | Only needed for building from source | [`documentation/install.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md) [From source](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md#L10-L16) |

### How the Dependencies Work

- **`@anthropic-ai/claude-agent-sdk`** — Handles model inference, streaming responses, and API authentication inheritance from Claude Code installations.

- **`p-limit`** — Caps parallel LLM calls to prevent rate limiting during the divergence phase.

- **`zod`** — Validates runtime options like `framesPerRun`, `topK`, and `concurrency` before execution.

## Setting Up the ADHD Skill: Five Installation Paths

### Method 1: Universal Agent Skill Install

The fastest path works with Claude Code, Claude Desktop, and other supported agents:

```bash
npx skills add UditAkhourii/adhd

```

This command auto-detects your active agent and installs [`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md) to the correct directory. See [`documentation/install.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md) [Universal install](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md#L7-L15).

### Method 2: Force Install for Codex or Special Agents

For agents that don't auto-detect (like Codex), specify the target and install globally:

```bash
npx skills add UditAkhourii/adhd -a codex -g

```

See [`documentation/install.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md) [Codex override](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md).

### Method 3: Manual Skill Installation

Direct download gives you full control over placement:

```bash
mkdir -p ~/.claude/skills/adhd
curl -fsSL https://raw.githubusercontent.com/UditAkhourii/adhd/main/skills/adhd/SKILL.md \
  -o ~/.claude/skills/adhd/SKILL.md

```

See [`documentation/install.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md) [Manual install](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md).

### Method 4: CLI Binary (No Agent Required)

Install the globally-exposed `adhd` command via npm:

```bash
npm install -g adhd-agent

```

Then invoke directly:

```bash

# Basic usage

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

# Custom parameters

adhd "name this function" \
  --frames 3 \
  --ideas 8 \
  --top 2 \
  --json > result.json

```

The CLI implementation lives in [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts), which parses arguments and delegates to the engine in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts).

### Method 5: Library Usage in TypeScript Projects

Embed the ADHD reasoning loop in your own applications:

```bash
npm install adhd-agent

```

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

const result = await run({
  problem: "How should we shard this queue under bursty load?",
  framesPerRun: 5,      // divergent frames to generate
  ideasPerFrame: 6,     // ideas per frame
  topK: 3,              // survivors to deepen
  concurrency: 4,       // parallel LLM calls (capped by p-limit)
  codeMode: true,       // bias toward engineering solutions
});

console.log(renderText(result));

```

The `run` function is exported from the package entry point and fully typed via `zod` schemas.

### Method 6: Build From Source

For development or customization:

```bash
git clone https://github.com/UditAkhourii/adhd.git
cd adhd && npm install && npm run build

```

See [`documentation/install.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md) [Build from source](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md#L10-L16).

## Advanced: Programmatic Skill Injection

For custom agent implementations using the Claude Agent SDK directly:

```typescript
import { query } from "@anthropic-ai/claude-agent-sdk";
import { readFileSync } from "node:fs";

const skill = readFileSync("./skills/adhd/SKILL.md", "utf8");

for await (const msg of query({
  prompt: "design a retry strategy for a CLI whose LLM hangs for 90s",
  options: {
    systemPrompt: { 
      type: "preset", 
      preset: "claude_code", 
      append: skill 
    },
    allowedTools: ["Task"], // enable skill's Task tool calls
  },
})) {
  // handle streaming response
}

```

## Key Source Files Reference

| File | Purpose | Direct Link |
|------|---------|-------------|
| [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json) | Node engine, dependencies, npm scripts | [View](https://github.com/UditAkhourii/adhd/blob/main/package.json) |
| [`documentation/install.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md) | Complete installation guide | [View](https://github.com/UditAkhourii/adhd/blob/main/documentation/install.md) |
| [`skills/adhd/SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md) | Skill definition loaded by agents | [View](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md) |
| [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) | CLI argument parsing and execution | [View](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) |
| [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) | Core orchestration: divergence → scoring → clustering → deepening | [View](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) |
| [`documentation/api.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/api.md) | Generated API reference | [View](https://github.com/UditAkhourii/adhd/blob/main/documentation/api.md) |

## Summary

- **Node.js 18+** is mandatory; check [`package.json`](https://github.com/UditAkhourii/adhd/blob/main/package.json) `engine` field for enforcement.
- **`ANTHROPIC_API_KEY`** must be exported in your environment for all usage modes.
- **Choose your install path**: `npx skills add` for agents, `npm install -g adhd-agent` for CLI, or `npm install adhd-agent` for library embedding.
- **Core runtime dependencies** (`@anthropic-ai/claude-agent-sdk`, `p-limit`, `zod`) install automatically via npm.
- **Source builds** require Git and follow standard `npm install && npm run build` workflow.

## Frequently Asked Questions

### What happens if I don't set `ANTHROPIC_API_KEY`?

The Claude Agent SDK attempts to inherit credentials from a Claude Code installation. If neither exists, API calls fail with authentication errors. The SDK does not prompt for credentials interactively.

### Can I run the ADHD skill offline?

No. All usage modes require internet access: the skill install fetches remote files via `npx`, and the reasoning loop calls Anthropic's Claude API. There is no local model fallback.

### How do I verify my installation works?

For CLI: run `adhd "test"` and confirm JSON output. For library: import `{ run }` and call with any problem string. For agent skill: check that your agent recognizes the `adhd` tool after restarting.

### What's the difference between `adhd-agent` and installing the skill?

`adhd-agent` is the **npm package** providing CLI and library APIs. The **skill** ([`SKILL.md`](https://github.com/UditAkhourii/adhd/blob/main/SKILL.md)) is a markdown definition that agents parse to expose the ADHD reasoning loop as a native tool. Both use the same [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) core but different entry points.