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
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 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.
Expand the full side-by-side
| 🟦 Baseline (single-shot) | 🟧 ADHD |
|---|---|
|
Walks through four textbook patterns:
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
|
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/adhdThen invoke explicitly with /adhd "your problem", or let it auto-trigger on ideation intents.
npm install -g adhd-agent # CLI
npm install adhd-agent # libraryCLI 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 2import { 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.clustersFull reference: documentation/api.md.
How it works
A two-phase loop with a hard wall between the phases.
- 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.
- 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
/researchskill, 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 · [email protected] · @UditAkhourii
Open to collaboration with research labs and applied-AI teams working on reasoning, planning, and agentic systems.
