How to Integrate UditAkhourii/adhd with Other Tools: Three Methods for the Ideation Engine

You can integrate the adhd parallel divergent ideation engine via NPM library imports, CLI execution, or Claude-compatible agent skills, exposing the core run function from src/engine.ts to any Node.js or shell environment.

The UditAkhourii/adhd repository implements a cognitive ideation system that generates multiple solution frames simultaneously using LLM-powered divergence and clustering. Because the architecture isolates core logic in a pure TypeScript function rather than a monolithic application, you can embed this capability into editors, CI pipelines, or agent frameworks. This guide covers the three integration methods supported by the codebase: programmatic library calls, command-line invocation, and skill-based agent integration.

Architecture Overview

The repository organizes functionality into three distinct layers to maximize reusability:

• CLI / Skill entry point (src/cli.ts): Parses user arguments, validates options, and formats output for terminal or JSON consumption.
• Engine (src/engine.ts): Orchestrates the diverge → score/cluster → deepen loop, managing frame selection, concurrency, and optional anchor stripping.
• Support modules: src/frames.ts defines cognitive frames, src/types.ts provides TypeScript interfaces for ideas and results, src/llm.ts wraps the Claude Agent SDK, and src/render.ts handles human-readable formatting.

This separation allows external tools to hook into any layer, from low-level engine calls to high-level CLI execution.

Integration Methods

Programmatic Integration via NPM Library

Import the adhd-agent package to embed ideation directly into Node.js applications. The main entry point is the run function exported from src/engine.ts, which accepts a RunOptions object and returns a RunResult promise.

Key parameters include:

• problem: The design challenge or coding task to solve.
• context: Optional code snippets or system constraints.
• framesPerRun: Number of cognitive frames to generate.
• ideasPerFrame: Solutions generated per frame.
• model: LLM identifier for generation (e.g., claude-3-5-sonnet-20240620).
• criticModel: Separate LLM for scoring and clustering (e.g., claude-3-opus-20240229).

// demo.ts
import { run } from "adhd-agent";

async function generateDesign() {
  const result = await run({
    problem: "Design a low-latency, fault-tolerant queue",
    context: "// Node.js, Redis-based, 10k RPS",
    framesPerRun: 6,
    ideasPerFrame: 8,
    topK: 3,
    model: "claude-3-5-sonnet-20240620",
    criticModel: "claude-3-opus-20240229",
  });

  console.log(result.shortlist.map(i => i.text));
}

This method suits VS Code extensions, custom LLM orchestrators, and CI pipelines that need to generate design proposals programmatically.

Shell Integration via CLI

For bash scripts, GitHub Actions, or ad-hoc terminal usage, install the adhd-agent package globally or run via npx to access the adhd command defined in src/cli.ts.

The CLI accepts positional arguments for the problem statement and flags for configuration:

• --frames: Number of frames to generate.
• --ideas: Ideas per frame.
• --top: Number of top results to return.
• --model and --critic-model: LLM specifications.
• --json: Output raw JSON for piping to tools like jq.

#!/usr/bin/env bash

# run-adhd.sh

PROBLEM="Add rate-limiting to API gateway"
adhd "$PROBLEM" \
  --frames 5 \
  --ideas 7 \
  --top 2 \
  --model claude-3-5-sonnet-20240620 \
  --critic-model claude-3-opus-20240229 \
  --json > result.json

jq '.shortlist[] | .text' result.json

The CLI handles parsing via src/cli.ts, invokes the engine, and renders results through src/render.ts or JSON serialization.

Agent Integration via Claude-Compatible Skills

The repository includes a YAML skill definition at skills/adhd/SKILL.md that registers an /adhd command within Claude-compatible agents like Claude Code, Cursor, or Codex.

Install the skill using the skills CLI:

npx skills add UditAkhourii/adhd

Once registered, agents can trigger the engine directly from chat:

/adhd "How can we make the build faster on CI?"

The skill forwards the prompt to the same run function used in programmatic integration, with results formatted through src/render.ts.

Customization and Extension Points

The engine exposes several extension mechanisms for domain-specific workflows:

Custom Frames: Modify the FRAMES array in src/frames.ts to add new cognitive perspectives or domain-specific lenses, then rebuild the package.

Model Selection: Pass distinct model and criticModel values to use different LLM families for generation versus evaluation, optimizing cost and accuracy.

Anchor Stripping: Control context contamination by setting stripAnchors (default true) in RunOptions or using --no-anchor-strip in CLI. This removes incidental references (like current stack traces) before divergence, improving independence across frames as implemented in src/engine.ts lines 31-41.

Summary

• Library Import: Import run from adhd-agent to embed ideation in Node.js applications, passing custom RunOptions to control frames, models, and output.
• CLI Execution: Use the adhd command with --json flags for shell scripts and automation pipelines that require machine-readable output.
• Agent Skills: Install via npx skills add UditAkhourii/adhd to enable /adhd commands in Claude Code, Cursor, or Codex.
• Customization: Extend frames in src/frames.ts, configure separate models for generation and criticism, and toggle anchor stripping via options or CLI flags.

Frequently Asked Questions

Can I integrate the adhd engine without installing it as a global package?

Yes. Use npx adhd-agent to run the CLI without installation, or import the package as a local dependency in your package.json. The engine requires only Node.js and does not depend on global system packages or specific environment configurations.

How do I customize the cognitive frames used during ideation?

Edit the FRAMES array in src/frames.ts to add, remove, or modify cognitive perspectives, then rebuild the package. Each frame represents a distinct lens (e.g., "security", "performance") through which the LLM evaluates the problem, allowing domain-specific customization of the divergence strategy.

What is the difference between the model and criticModel parameters?

The model parameter specifies the LLM used for generating initial ideas across frames, while criticModel designates a potentially different LLM for scoring, clustering, and selecting the top-K results. This separation allows you to use faster, cheaper models for generation and more powerful models for evaluation, optimizing both cost and quality as defined in src/types.ts and implemented in src/engine.ts.

Is the CLI output machine-readable for automation pipelines?

Yes. Pass the --json flag to the adhd command to receive structured JSON output containing the full RunResult object, including the shortlist array of top ideas. This integrates cleanly with jq, GitHub Actions, or any tool that parses JSON streams, as handled by the output logic in src/cli.ts.

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