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

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 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 engine field
ANTHROPIC_API_KEY	Authenticates Claude API calls via the Claude Agent SDK	documentation/install.md Auth section
Core dependencies	Runtime libraries: @anthropic-ai/claude-agent-sdk, p-limit, zod	package.json dependencies
Internet access	Required for npx skills add and API calls	documentation/install.md One-command install
Git (optional)	Only needed for building from source	documentation/install.md From source

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:

npx skills add UditAkhourii/adhd

This command auto-detects your active agent and installs SKILL.md to the correct directory. See documentation/install.md Universal install.

Method 2: Force Install for Codex or Special Agents

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

npx skills add UditAkhourii/adhd -a codex -g

See documentation/install.md Codex override.

Method 3: Manual Skill Installation

Direct download gives you full control over placement:

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 Manual install.

Method 4: CLI Binary (No Agent Required)

Install the globally-exposed adhd command via npm:

npm install -g adhd-agent

Then invoke directly:

# 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, which parses arguments and delegates to the engine in src/engine.ts.

Method 5: Library Usage in TypeScript Projects

Embed the ADHD reasoning loop in your own applications:

npm install adhd-agent

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:

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

See documentation/install.md Build from source.

Advanced: Programmatic Skill Injection

For custom agent implementations using the Claude Agent SDK directly:

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	Node engine, dependencies, npm scripts	View
documentation/install.md	Complete installation guide	View
skills/adhd/SKILL.md	Skill definition loaded by agents	View
src/cli.ts	CLI argument parsing and execution	View
src/engine.ts	Core orchestration: divergence → scoring → clustering → deepening	View
documentation/api.md	Generated API reference	View

Summary

• Node.js 18+ is mandatory; check 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) is a markdown definition that agents parse to expose the ADHD reasoning loop as a native tool. Both use the same src/engine.ts core but different entry points.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}