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

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 but differing in entry points, distribution mechanisms, and runtime environments.

The 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, 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.

# 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. The CLI entry point at 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.

npx skills add UditAkhourii/adhd

This command copies the 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.

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, 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.

Skill Method: The entry point is the 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

# 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 processes these flags and calls renderText or outputs raw JSON based on your selection.

Adding the Skill to an Agent

# 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 and routes the command to the ADHD engine automatically.

Programmatic Usage in 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: CLI entry point handling argument parsing, environment setup, and result formatting via renderText.
• src/engine.ts: Core engine containing the run function that fans out frames, scores ideas, clusters results, and performs deep analysis.
• src/render.ts: Human-readable text formatter used exclusively by the CLI for terminal output.
• skills/adhd/SKILL.md: Declarative skill definition registering the /adhd command with agent systems.
• 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, ensuring identical ideation quality.
• Different entry points: src/cli.ts handles shell interactions while 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 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. The output differences are limited to formatting: the CLI uses renderText from 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, 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. 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.

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