How to Configure UditAkhourii/adhd: Complete Setup Guide for Skill, CLI, and Library

Configure UditAkhourii/adhd by adjusting the RunOptions object—defined in src/types.ts—through CLI flags, library parameters, or skill variables to control divergence frames, model selection, and concurrency limits.

The adhd (Parallel Divergent Ideation) repository provides a configurable framework for structured brainstorming across three deployment modes. Whether you install it as a Claude skill, a global CLI tool, or a TypeScript library, all entry points share the same core configuration interface implemented in the source code.

Understanding the Core RunOptions Interface

Configuration centers on the RunOptions type exported from [src/types.ts](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts). This object controls the divergence-convergence loop orchestrated by the run() function in [src/engine.ts](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts).

The complete interface includes:

• problem (string, required) – The problem statement to explore
• context (string, optional) – Code or constraints to ground the ideation
• framesPerRun (number, default: 5) – Parallel cognitive frames to initiate
• ideasPerFrame (number, default: 6) – Raw ideas generated per frame
• topK (number, default: 3) – Ideas surviving critique to deepen in Phase 2
• concurrency (number, default: 4) – Simultaneous LLM calls allowed
• codeMode (boolean, default: true) – Bias frames toward engineering when true
• stripAnchors (boolean, default: true) – Remove incidental anchors before fan-out
• model (string, optional) – Override generator and critic model (e.g., claude-3-5-sonnet-20240620)
• criticModel (string, optional) – Override critic-only model to decorrelate errors
• onEvent (function, optional) – Hook receiving RunEvent for progress streaming

Increasing framesPerRun broadens the search space but raises API costs, while adjusting topK controls how many ideas receive detailed sketching after initial critique.

Configuring ADHD by Deployment Mode

Skill Mode (Agent Integration)

Install the skill using the auto-detection installer:

npx skills add UditAkhourii/adhd

Configuration passes through variables embedded in [skills/adhd/SKILL.md](https://github.com/UditAkhourii/adhd/blob/main/skills/adhd/SKILL.md). When invoking via the Claude-Code SDK, append the skill content to the system prompt:

import { readFileSync } from "node:fs";
const skill = readFileSync("./skills/adhd/SKILL.md", "utf8");

await query({
  prompt: "design a secure token bucket limiter",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code", append: skill },
    allowedTools: ["Task"],
    // Variables like frames: 7, ideas: 8, top: 4 are parsed from the skill body
  },
});

The skill's pre-flight gate reads these variables and forwards them to the library run() call.

CLI Mode (Global Command)

When installed globally, invoke adhd with flags that map directly to RunOptions properties:

# Basic usage with defaults (5 frames, 6 ideas/frame, top-3)

adhd "design a rate limiter that survives leader election"

# Override configuration via CLI flags

adhd "optimise the caching layer" \
    --frames 7 \
    --ideas 10 \
    --top 4 \
    --model claude-3-5-sonnet-20240620 \
    --critic-model claude-3-opus-20240229 \
    --concurrency 6

Disable code-mode bias with --no-code-mode or preserve anchors with --no-anchor-strip. See [documentation/api.md](https://github.com/UditAkhourii/adhd/blob/main/documentation/api.md) for the complete CLI flag reference.

Library Mode (TypeScript/Node.js)

Import the run function from adhd-agent and pass a fully typed RunOptions object:

import { run, renderText } from "adhd-agent";
import { readFileSync } from "node:fs";

const result = await run({
  problem: "how to shard a high-throughput queue",
  context: readFileSync("./queue.ts", "utf8"),
  framesPerRun: 6,
  ideasPerFrame: 8,
  topK: 4,
  concurrency: 5,
  model: "claude-3-5-sonnet-20240620",
  criticModel: "claude-3-opus-20240229",
  onEvent: (e) => console.error(e), // Stream progress to stderr
});

console.log(renderText(result));

The run() call returns a RunResult object containing structured data for programmatic processing.

Authentication Requirements

All modes require an ANTHROPIC_API_KEY environment variable. Set it before running:

export ANTHROPIC_API_KEY=sk-your-key-here

The SDK automatically detects this variable. Do not commit this key to source control—the repository contains no secrets.

Customizing Cognitive Frames

Frames are the cognitive lenses driving divergence. The default set resides in [src/frames.ts](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts), exported as the FRAMES constant. To modify frames:

1. Edit src/frames.ts entries following the Frame type (id, label, prompt, tags)
2. Rebuild the package (npm run build) for library changes
3. For skill-only modifications, update SKILL.md to reference new frame IDs
4. Use the exported selectFrames helper for deterministic selection in custom code

Configuration Quick Reference

Option	CLI Flag	Library Property	Default
Frames per run	--frames N	framesPerRun	5
Ideas per frame	--ideas N	ideasPerFrame	6
Top-K deepened	--top N	topK	3
Parallel LLM calls	--concurrency N	concurrency	4
Disable code-bias	--no-code-mode	codeMode: false	true
Keep anchors	--no-anchor-strip	stripAnchors: false	true
Generator model	--model NAME	model	SDK default
Critic model	--critic-model NAME	criticModel	inherits model
JSON output	--json	–	raw RunResult

Summary

• Core configuration happens through the RunOptions interface in src/types.ts, controlling breadth (framesPerRun), depth (topK), and parallelism (concurrency)
• Three modes (Skill, CLI, Library) share identical underlying options but expose them via environment variables, CLI flags, or function parameters respectively
• Model splitting allows using a cheaper model for generation and a stronger model for critique via model and criticModel
• Frame customization requires editing src/frames.ts and rebuilding for library usage, or modifying SKILL.md for agent deployments
• Authentication relies exclusively on the ANTHROPIC_API_KEY environment variable

Frequently Asked Questions

What file contains the TypeScript definitions for configuration options?

The RunOptions and RunResult types are defined in [src/types.ts](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts). This file serves as the source of truth for all configurable parameters across Skill, CLI, and Library modes.

How do I prevent the tool from biasing toward coding solutions?

Set codeMode to false (CLI: --no-code-mode). When disabled, the frame selector in src/engine.ts ignores tags like code or design, making the ideation suitable for product strategy or pure design problems rather than engineering solutions.

Can I use different models for idea generation and critique?

Yes. Specify model for the generation phase and criticModel for the evaluation phase. For example, use claude-3-5-sonnet-20240620 for generation and claude-3-opus-20240229 for critique to decorrelate errors while managing costs.

Where should I set the ANTHROPIC_API_KEY for CLI usage?

Export the ANTHROPIC_API_KEY environment variable in your shell or .env file before invoking the adhd command. The CLI and underlying SDK automatically detect this variable; no configuration file is required.

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