UditAkhourii/adhd

ADHD — a skill for agents

🎮 Join the Discord → for frame design, eval problems, and trap-hunting in real time · 👉 Join the community → as a contributor, maintainer, or early adopter (one short form).

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…".

📚 Official docs: adhd.mintlify.site · 📄 Preprint: ADHD: Parallel Divergent Ideation for Coding Agents · 👤 Author: Udit Akhouri — @akhouriudit · LinkedIn

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

Baseline gives the sensible textbook hybrid (staged timeouts + one auto-retry) — the answer a senior engineer gives in 30 seconds, with no traps named. ADHD spawns 6 isolated frames, surfaces 30+ ideas, flags 20 traps with reasons, and lands the non-obvious pick baseline never considers: the slow model might just be the wrong model for this prompt — instant abort + branch to a cheaper/faster one.

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

---

Featured

• 🔌 Adopted by repowire — the first OSS project to officially ship ADHD, ported onto its mesh-orchestrator primitives in PR #313 (merged).
• 📰 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.

Early adopters

17+ projects ship or integrate ADHD — including repowire, mstack, zk-flow-oss, han, wtfismyrepo, and awesome-prompts. The full table of who shipped what lives in ADOPTERS.md.

Shipping ADHD in your project? Open a PR adding yourself to ADOPTERS.md, 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.

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

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

---

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.

| Dimension | ADHD | Baseline | Δ | Ratio | | ------------------ | -------: | -------: | --------: | ----: | | breadth | 9.00 | 4.83 | +4.17 | 1.9× | | novelty | 7.83 | 2.67 | +5.17 | 2.9× | | trap detection | 9.50 | 1.83 | +7.67 | 5.2× | | actionability | 9.50 | 6.50 | +3.00 | 1.5× | | builder usefulness | 7.67 | 6.83 | +0.83 | 1.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

📚 Official docs: adhd.mintlify.site — the full, browsable documentation site.

In-repo pages:

| Page | What's in it | |---|---| | Quickstart | First skill, CLI, and TypeScript runs with practical commands | | Install | Every install path — skill, CLI, library, Agent SDK, per-platform | | How it works | The two-phase loop + architecture (context, pruning, orchestration) | | vs CoT & ToT | Structural comparison, the three load-bearing differences, frames vs personas | | Frames | The 15 cognitive frames, how selection works, how to author your own | | When to use | Use / don't use, why it shines on creative work, cost & speed | | CLI & API | CLI flags, library types, using ADHD inside your own agent | | Evals | Methodology, headline numbers, limitations, roadmap |

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

---

Star History

---

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.