ADHD

July 23, 2026 ยท View on GitHub

ADHD for Claude Code

ADHD โ€” a skill for agents

CI npm license Node Paper Featured: The New Stack Discord

UditAkhourii%2Fadhd | Trendshift

๐ŸŽฎ Join the ADHD Discord โ†’

This is where the real-time thinking happens: frame design, eval problems, trap-hunting, and neurodivergence-inspired research on reasoning architectures. If you've got opinions on premature convergence, cognitive frames, or just want to argue about the next eval problem โ€” come argue with us live.

๐Ÿ‘‰ Join the ADHD community โ†’ as a contributor, maintainer, early adopter, or just a member. One short form. We coordinate frame contributions, eval problems, integrations, and adopter onboarding there.

An architectural fix for premature convergence in autoregressive reasoning.

Linear Chain-of-Thought anchors on whatever it says first. Tree-of-Thought widens the search but still walks a single shared context, so the anchoring persists across branches. ADHD treats this as an architectural problem, not a prompting one โ€” it spawns N isolated reasoning processes under deliberately distorted cognitive frames, with zero shared context during divergence, then runs a separate critic pass to score, cluster, prune traps, and deepen the survivors.

Reach for it on design decisions, fuzzy debugging, naming, API surface design, strategy, and any prompt of the shape "give me a few ways toโ€ฆ".

๐Ÿ“„ Preprint: ADHD: Parallel Divergent Ideation for Coding Agents ยท ๐Ÿ‘ค Author: Udit Akhouri โ€” @akhouriudit ยท LinkedIn

Side-by-side: baseline vs ADHD

One eval problem, same model, two strategies. Full transcripts in bench/results.json.

Problem. "We have a CLI that calls an LLM and it sometimes hangs for 90 seconds. Design the right retry/timeout/UX strategy."

๐ŸŸฆ Baseline (single-shot) ๐ŸŸง ADHD

Walks through four textbook patterns:

  1. Progressive timeout with staged UI (10s / 30s / 60s)
  2. Fast-fail + exponential backoff retry
  3. Hedged parallel requests
  4. Streaming with keepalive

Lands on a hybrid recommendation โ€” 15s first-token timeout, 30s between-token timeout, 90s absolute, one auto-retry. Sensible. Google SRE Book ch. 22. The answer a senior engineer gives in 30 seconds.

What's missing: no traps named, no acknowledgement that the user might want to bail out of a slow request, no questioning of the "wait then retry the same model" frame.

Spawns 6 isolated frames, surfaces a wide set of 30+ ideas across economic-incentive, async-control-surface, gamification, perceptual-distortion, collective-intelligence, redundancy-race clusters, then:

  • โ˜… Non-obvious pick: "rage-quit = instant abort + branch to cheaper/faster model" โ€” a button that pulses hotter the longer you wait. One click cancels and re-submits to Haiku-class. The thing baseline never considers: the slow model might just be the wrong model for this prompt.
  • Plus shortlist: scout-fork to alternate endpoints at 30s; daemonize the CLI with ticket IDs; race 3 LLM replicas, cache the winner.
  • 20 traps flagged with one-line reasons โ€” including the cute "stream tokens in reverse" and "patience-token billing" ideas before they cost engineering time.

Independent LLM judge on this problem: breadth 9 vs 6, novelty 8 vs 3, trap detection ~8 vs ~2. Methodology in documentation/evals.md.

  • ๐Ÿ”Œ Adopted by repowire โ€” the first OSS project to officially ship ADHD. Its maintainer ported the framework onto repowire's mesh-orchestrator primitives in PR #313 (merged): frames become frame-shifted temp peers, the generator/critic split maps onto separate peers vs. the orchestrator's own turn, attribution via metadata.based-on (MIT).
  • ๐Ÿ“ฐ The New Stack ran a feature story on ADHD for Claude Code.
  • ๐Ÿ’ฌ OpenClaw / multi-agent community is independently testing it across agents. One tester: "I read it, installed it on two different agentsโ€ฆ I actually love it. This is great. I thought this was gonna be another useless post. But no, it wasn't."
  • ๐Ÿ”ฌ An independent evidence-based research review (11 sources, 8 validation rounds) was published against the method โ€” findings tracked openly as issues #16โ€“#18.

Community

๐Ÿ‘‰ Join the ADHD community โ†’ as a contributor, maintainer, early adopter, or just a member. One short form. We coordinate frame contributions, eval problems, integrations, and adopter onboarding there.

Early adopters

Projects that officially ship or integrate ADHD:

ProjectWhat they didStatus
repowirePorted ADHD onto repowire's mesh-orchestrator primitives โ€” frames become frame-shifted temp peers, generator/critic split maps to separate peers vs. the orchestrator's turn. Ships in the default orchestrator template. (PR #313)โœ… Merged ยท MIT attribution
mstackVendored ADHD as the think plugin in their Claude plugin marketplace โ€” wires the divergent-then-converge loop into mstack for architecture, naming, API design, and fuzzy debugging.โœ… Shipped ยท MIT attribution
zk-flow-ossAdapted ADHD's IDEATION_FRAMES into their critique workflow (src/workflows/critique.src.js) as a pre-pass to reduce anchoring bias before review.โœ… Shipped ยท MIT attribution
hanPublished an evidence-based research application of ADHD onto Han's plugin model โ€” 11 sources, 8 validation rounds. Findings landed as issues #16โ€“#18.โœ… Research integration
app-library (yslee5005)Built an expert-thinker MoAI agent on the ADHD pattern โ€” tree-of-thought with isolated divergence and a separate critic pass.โœ… Shipped
striatumInstaller scaffold for Claude Code recommends npx skills add UditAkhourii/adhd for architecture, API design, and naming work.โœ… Shipped
awesome-promptsPackaged the ADHD loop as a standalone prompt (adhd_parallel_ideation_skill.txt) for users without the skill installed.โœ… Shipped
nix-skillsNix packaging of the ADHD skill (pinned to commit 770834e) for the Nix-based agent-skills ecosystem.โœ… Shipped
caioniehues/adhdFork with a customized SKILL.md that re-points install + docs to their own distribution while keeping upstream attribution.โœ… Fork ยท attribution
ktg-one/adhdFork used as a personal "codified model of how my brain works" โ€” wired into the may-2026-kb knowledge base as a cognitive-architecture pattern.โœ… Fork ยท in use
wtfismyrepoUses ADHD as the explanation engine for codebase onboarding. The deterministic layer (import-graph PageRank, git-churn fragility, GitHub PR/issue signals) produces an analysis object that is formatted as an ADHD problem + context. The ADHD divergeโ†’scoreโ†’clusterโ†’deepen loop then generates onboarding angles across 12 codebase-specific frames (new-grad, archeologist, security-researcher, on-call-at-3am, refactorer, inversion, โ€ฆ), scores them for fit to the developer's level + goal, prunes traps, and deepens the non-obvious pick into a full walkthrough. Ships the ADHD method in the Claude Code skill (SKILL.md) with zero extra deps โ€” Claude runs the frames itself.โœ… Shipped ยท MIT attribution
mythifyAdded trap-clause and alternatives guidance to its analysis prompt packet after evaluating ADHD's divergent-frames-then-critic pattern โ€” surfaces "the one that looks good but isn't, and why" before a plan is committed to. (PR #18)โœ… Merged
godauditsShipped v2.11.0 adopting measurement and provenance discipline from an ADHD review โ€” an independent refutation pass (refute plan/apply), severity-aware recall metrics, and attribution/limits tracking on eval results. (PR #13)โœ… Shipped
godplansShipped v1.8.0 turning its self-audit into an independent audit gate (separate scoring pass, isolated context) and adding a no-skill baseline control arm to its eval harness, inspired by ADHD's generator/critic split โ€” while explicitly rejecting the novelty-scoring axis and randomized frame selection as unsuited to its own goals. (PR #8)โœ… Shipped
Claude1.0 (Ro-Sama-33)Installed the ADHD skill into .agents/skills/adhd/. (PR #16)โœ… Installed

Shipping ADHD in your project? Open a PR adding it here, or open an issue and we'll add you.

Install

One command, auto-detects your agent (Claude Code, Cursor, Antigravity, Codex, Cline, Gemini CLI, Windsurf, and ~50 more):

npx skills add UditAkhourii/adhd

Then invoke explicitly with /adhd "your problem", or let it auto-trigger on ideation intents.

Codex quick path

If the universal command above fails to register inside Codex (some Codex builds discover skills from a specific path), force the target:

npx skills add UditAkhourii/adhd -a codex -g

Or install manually into Codex's skills directory:

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

Restart Codex. /adhd "design a rate limiter" should now route through the skill. The skill ships with a single-line description (โ‰ค600 chars) specifically because some Codex builds truncate or reject multi-line YAML block descriptions.

CLI and library installs, manual curl for other agents, and per-platform paths are in documentation/install.md.

npm install -g adhd-agent     # CLI
npm install adhd-agent        # library

Quickstart

adhd "design a rate limiter that survives a leader election"
adhd "name this function" --frames 3 --ideas 8 --top 2

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

const result = await run({ problem: "How should we shard this queue under bursty load?", framesPerRun: 5, topK: 3 });
console.log(renderText(result));
// result.shortlist ยท result.nonObviousPick ยท result.traps ยท result.deepened ยท result.clusters

Full reference: documentation/api.md.

How it works

A two-phase loop with a hard wall between the phases.

  1. Diverge. Pick N cognitive frames. Spawn N parallel, isolated Agent calls โ€” each sees the problem plus one frame's vantage prompt, and a system prompt that forbids evaluation. Branches never see each other, so no anchoring.
  2. Focus. A separate critic call scores every idea (novelty / viability / fit), flags traps with reasons, clusters by underlying angle, and deepens the top-K survivors into sketches with risks and first steps.

The generator-critic split is mechanical โ€” separate LLM calls with opposite system prompts โ€” not promised in one prompt. Deep dive: documentation/how-it-works.md. How it differs from CoT and ToT: documentation/vs-cot-and-tot.md.

Results

Mean scores across 6 open-ended engineering problems (0โ€“10), ADHD vs a single-shot baseline at the same model, judged by an independent LLM with a skeptical-staff-engineer prompt, A/B order randomized.

DimensionADHDBaselineฮ”Ratio
breadth9.004.83+4.171.9ร—
novelty7.832.67+5.172.9ร—
trap detection9.501.83+7.675.2ร—
actionability9.506.50+3.001.5ร—
builder usefulness7.676.83+0.831.1ร—

ADHD wins 5 of 6 problems. Biggest gap is trap detection โ€” baselines rarely name the seductive-but-broken ideas. Methodology, limitations, and how to reproduce: documentation/evals.md.

Documentation

PageWhat's in it
QuickstartFirst skill, CLI, and TypeScript runs with practical commands
InstallEvery install path โ€” skill, CLI, library, Agent SDK, per-platform
How it worksThe two-phase loop + architecture (context, pruning, orchestration)
vs CoT & ToTStructural comparison, the three load-bearing differences, frames vs personas
FramesThe 15 cognitive frames, how selection works, how to author your own
When to useUse / don't use, why it shines on creative work, cost & speed
CLI & APICLI flags, library types, using ADHD inside your own agent
EvalsMethodology, headline numbers, limitations, roadmap

Also: SKILL.md (the runnable skill) ยท SOURCE-SPEC.md (original spec) ยท CONTRIBUTING.md ยท the preprint.

Star History

Star History

Star History Chart

External reviews

  • Han plugin compatibility analysis by @mxriverlynn โ€” evidence-based review using Han's own /research skill, 11 sources, 8 validation rounds. Findings tracked as issues #16, #17, #18.
  • A measured duel vs. single-shot by Shichinomiya (@shichinomiya_s) โ€” independent blind-scored benchmark (2 problems, LLM-as-judge, A/B positions swapped). ADHD won both, with the biggest gains in novelty (4.5โ†’9.0) and trap detection (5.0โ†’9.0), at a real cost of ~2.3ร— time and ~1.9ร— output.

License

MIT License.

ADHD operationalizes the Divergent Ideation source spec (SOURCE-SPEC.md). The runnable skill is at skills/adhd/SKILL.md.

Contact

Udit Akhouri โ€” author of the preprint and maintainer.

adhdstack.github.io ยท @akhouriudit ยท LinkedIn ยท researchudit@gmail.com ยท @UditAkhourii

Open to collaboration with research labs and applied-AI teams working on reasoning, planning, and agentic systems.