Skip to content
Back to search

adhd

MarketplaceWorks with Claude CodeGitHub

ADHD — a skill for coding agents. Tree-of-thought with pruning, built on the Claude & Codex Agent SDK. Fans out parallel divergent thoughts under different cognitive frames, scores, prunes traps, deepens the survivors. The no-brainer skill for creative and interdisciplinary work.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/uditakhourii-adhd/badge.svg)](/listings/uditakhourii-adhd)

HTML

<a href="/listings/uditakhourii-adhd"><img src="/api/listings/uditakhourii-adhd/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](./documentation/install.md)**.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 29 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "adhd",
  3. "owner": {
  4. "name": "ADHD contributors",
  5. "url": "https://github.com/UditAkhourii/adhd"
  6. },
  7. "plugins": [
  8. {
  9. "name": "adhd",
  10. "source": "./",
  11. "description": "Parallel divergent ideation for coding agents: fans out isolated branches under different cognitive frames, scores, clusters, prunes traps, and deepens the survivors.",
  12. "version": "0.1.4",
  13. "author": {
  14. "name": "ADHD contributors"
  15. },
  16. "homepage": "https://github.com/UditAkhourii/adhd#readme",
  17. "repository": "https://github.com/UditAkhourii/adhd",
  18. "license": "MIT",
  19. "category": "productivity",
  20. "keywords": [
  21. "ideation",
  22. "brainstorm",
  23. "divergent-thinking",
  24. "tree-of-thought",
  25. "architecture"
  26. ]
  27. }
  28. ]
  29. }
README.md · README · 217 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <a href="https://adhdstack.github.io/">
  2. <img src="docs/hero.png" alt="ADHD for Claude Code" width="100%">
  3. </a>
  4. </p>
  5. # ADHD — a skill for agents
  6. [![CI](https://github.com/UditAkhourii/adhd/actions/workflows/ci.yml/badge.svg)](https://github.com/UditAkhourii/adhd/actions/workflows/ci.yml)
  7. [![npm](https://img.shields.io/npm/v/adhd-agent.svg)](https://www.npmjs.com/package/adhd-agent)
  8. [![Docs](https://img.shields.io/badge/docs-adhd.mintlify.site-0EA5E9)](https://adhd.mintlify.site/)
  9. [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
  10. [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](./documentation/install.md)
  11. [![Paper](https://img.shields.io/badge/paper-preprint-blueviolet)](https://adhdstack.github.io/)
  12. [![Featured: The New Stack](https://img.shields.io/badge/featured-The%20New%20Stack-ff5500)](https://thenewstack.io/claude-code-adhd/)
  13. [![Discord](https://img.shields.io/badge/Discord-Join%20the%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/PZcRzjXQah)
  14. <a href="https://trendshift.io/repositories/39300?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-39300" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/39300/daily?language=TypeScript" alt="UditAkhourii%2Fadhd | Trendshift" width="250" height="55"/></a>
  15. > 🎮 [**Join the Discord →**](https://discord.gg/PZcRzjXQah) for frame design, eval problems, and trap-hunting in real time · 👉 [**Join the community →**](https://tally.so/r/WO1Nzj) as a contributor, maintainer, or early adopter (one short form).
  16. > **An architectural fix for premature convergence in autoregressive reasoning.**
  17. 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.
  18. 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…"***.
  19. 📚 **Official docs:** [adhd.mintlify.site](https://adhd.mintlify.site/) · 📄 **Preprint:** [ADHD: Parallel Divergent Ideation for Coding Agents](https://adhdstack.github.io/) · 👤 **Author:** Udit Akhouri — [@akhouriudit](https://x.com/akhouriudit) · [LinkedIn](https://www.linkedin.com/in/udit-akhouri-10160a168/)
  20. ---
  21. ## Side-by-side: baseline vs ADHD
  22. One eval problem, same model, two strategies. Full transcripts in [`bench/results.json`](./bench/results.json).
  23. > **Problem.** *"We have a CLI that calls an LLM and it sometimes hangs for 90 seconds. Design the right retry/timeout/UX strategy."*
  24. 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.
  25. <details>
  26. <summary><strong>Expand the full side-by-side</strong></summary>
  27. <table>
  28. <tr>
  29. <th width="50%">🟦 Baseline (single-shot)</th>
  30. <th width="50%">🟧 ADHD</th>
  31. </tr>
  32. <tr valign="top">
  33. <td>
  34. Walks through four **textbook** patterns:
  35. 1. Progressive timeout with staged UI (10s / 30s / 60s)
  36. 2. Fast-fail + exponential backoff retry
  37. 3. Hedged parallel requests
  38. 4. Streaming with keepalive
  39. 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.
  40. **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.
  41. </td>
  42. <td>
  43. 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:
  44. - ★ **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.**
  45. - Plus shortlist: scout-fork to alternate endpoints at 30s; daemonize the CLI with ticket IDs; race 3 LLM replicas, cache the winner.
  46. - **20 traps flagged with one-line reasons** — including the cute "stream tokens in reverse" and "patience-token billing" ideas before they cost engineering time.
  47. </td>
  48. </tr>
  49. </table>
  50. </details>
  51. Independent LLM judge on this problem: **breadth 9 vs 6, novelty 8 vs 3, trap detection ~8 vs ~2.** Methodology in [documentation/evals.md](./documentation/evals.md).
  52. ---
  53. ## Featured
  54. - 🔌 **Adopted by [repowire](https://github.com/prassanna-ravishankar/repowire)** — the first OSS project to officially ship ADHD, ported onto its mesh-orchestrator primitives in [PR #313](https://github.com/prassanna-ravishankar/repowire/pull/313) (merged).
  55. - 📰 **[The New Stack](https://thenewstack.io/claude-code-adhd/)** ran a feature story on ADHD for Claude Code.
  56. - 💬 **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."*
  57. - 🔬 An independent **[evidence-based research review](https://github.com/testdouble/han/blob/adhd-swarm-research/docs/research/adhd-application-to-han.md)** (11 sources, 8 validation rounds) was published against the method — findings tracked openly as [issues #16–#18](https://github.com/UditAkhourii/adhd/issues).
  58. ---
  59. ## Early adopters
  60. **17+ projects** ship or integrate ADHD — including [repowire](https://github.com/prassanna-ravishankar/repowire), [mstack](https://github.com/mayank-io/mstack), [zk-flow-oss](https://github.com/matt-metivier/zk-flow-oss), [han](https://github.com/testdouble/han), [wtfismyrepo](https://github.com/nandnijaiswal/wtfismyrepo), and [awesome-prompts](https://github.com/ai-boost/awesome-prompts). The full table of who shipped what lives in **[ADOPTERS.md](./ADOPTERS.md)**.
  61. Shipping ADHD in your project? Open a PR adding yourself to [ADOPTERS.md](./ADOPTERS.md), or [open an issue](https://github.com/UditAkhourii/adhd/issues/new) and we'll add you.
  62. ---
  63. ## Install
  64. One command, auto-detects your agent (Claude Code, Cursor, Antigravity, Codex, Cline, Gemini CLI, Windsurf, and ~50 more):
  65. ```bash
  66. npx skills add UditAkhourii/adhd
  67. ```
  68. Then invoke explicitly with `/adhd "your problem"`, or let it auto-trigger on ideation intents.
  69. ```bash
  70. npm install -g adhd-agent # CLI
  71. npm install adhd-agent # library
  72. ```
  73. CLI and library installs, the Codex quick path, manual curl for other agents, and per-platform paths are in **[documentation/install.md](./documentation/install.md)**.
  74. ---
  75. ## Quickstart
  76. ```bash
  77. adhd "design a rate limiter that survives a leader election"
  78. adhd "name this function" --frames 3 --ideas 8 --top 2
  79. ```
  80. ```ts
  81. import { run, renderText } from "adhd-agent";
  82. const result = await run({ problem: "How should we shard this queue under bursty load?", framesPerRun: 5, topK: 3 });
  83. console.log(renderText(result));
  84. // result.shortlist · result.nonObviousPick · result.traps · result.deepened · result.clusters
  85. ```
  86. Full reference: **[documentation/api.md](./documentation/api.md)**.
  87. ---
  88. ## How it works
  89. A two-phase loop with a hard wall between the phases.
  90. 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.
  91. 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.
  92. 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](./documentation/how-it-works.md)**. How it differs from CoT and ToT: **[documentation/vs-cot-and-tot.md](./documentation/vs-cot-and-tot.md)**.
  93. ---
  94. ## Results
  95. 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.
  96. | Dimension | ADHD | Baseline | Δ | Ratio |
  97. | ------------------ | -------: | -------: | --------: | ----: |
  98. | breadth | **9.00** | 4.83 | **+4.17** | 1.9× |
  99. | novelty | **7.83** | 2.67 | **+5.17** | 2.9× |
  100. | trap detection | **9.50** | 1.83 | **+7.67** | 5.2× |
  101. | actionability | **9.50** | 6.50 | **+3.00** | 1.5× |
  102. | builder usefulness | **7.67** | 6.83 | **+0.83** | 1.1× |
  103. **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/evals.md)**.
  104. ---
  105. ## Documentation
  106. 📚 **Official docs:** [**adhd.mintlify.site**](https://adhd.mintlify.site/) — the full, browsable documentation site.
  107. In-repo pages:
  108. | Page | What's in it |
  109. |---|---|
  110. | [Quickstart](./documentation/quickstart.md) | First skill, CLI, and TypeScript runs with practical commands |
  111. | [Install](./documentation/install.md) | Every install path — skill, CLI, library, Agent SDK, per-platform |
  112. | [How it works](./documentation/how-it-works.md) | The two-phase loop + architecture (context, pruning, orchestration) |
  113. | [vs CoT & ToT](./documentation/vs-cot-and-tot.md) | Structural comparison, the three load-bearing differences, frames vs personas |
  114. | [Frames](./documentation/frames.md) | The 15 cognitive frames, how selection works, how to author your own |
  115. | [When to use](./documentation/when-to-use.md) | Use / don't use, why it shines on creative work, cost & speed |
  116. | [CLI & API](./documentation/api.md) | CLI flags, library types, using ADHD inside your own agent |
  117. | [Evals](./documentation/evals.md) | Methodology, headline numbers, limitations, roadmap |
  118. Also: [SKILL.md](./skills/adhd/SKILL.md) (the runnable skill) · [SOURCE-SPEC.md](./SOURCE-SPEC.md) (original spec) · [CONTRIBUTING.md](./CONTRIBUTING.md) · [the preprint](https://adhdstack.github.io/).
  119. ---
  120. ## Star History
  121. <a href="https://www.star-history.com/?repos=UditAkhourii%2Fadhd&type=date&legend=top-left">
  122. <picture>
  123. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=UditAkhourii/adhd&type=date&theme=dark&legend=top-left&sealed_token=_61--Q_Ev0_B7e-nUMAMTCYQJixOhQGyQyXO-6nA_AKqyBlPVkAOPJaoKq2mnzIhIP77I4hbSo1TdytVtrd5vNQHAN3-aL5Zn-KTGh1-AYEV77E68uZChA" />
  124. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=UditAkhourii/adhd&type=date&legend=top-left&sealed_token=_61--Q_Ev0_B7e-nUMAMTCYQJixOhQGyQyXO-6nA_AKqyBlPVkAOPJaoKq2mnzIhIP77I4hbSo1TdytVtrd5vNQHAN3-aL5Zn-KTGh1-AYEV77E68uZChA" />
  125. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=UditAkhourii/adhd&type=date&legend=top-left&sealed_token=_61--Q_Ev0_B7e-nUMAMTCYQJixOhQGyQyXO-6nA_AKqyBlPVkAOPJaoKq2mnzIhIP77I4hbSo1TdytVtrd5vNQHAN3-aL5Zn-KTGh1-AYEV77E68uZChA" />
  126. </picture>
  127. </a>
  128. ---
  129. ## External reviews
  130. - [**Han plugin compatibility analysis**](https://github.com/testdouble/han/blob/adhd-swarm-research/docs/research/adhd-application-to-han.md) by [@mxriverlynn](https://www.reddit.com/user/mxriverlynn) — evidence-based review using Han's own `/research` skill, 11 sources, 8 validation rounds. Findings tracked as issues [#16](https://github.com/UditAkhourii/adhd/issues/16), [#17](https://github.com/UditAkhourii/adhd/issues/17), [#18](https://github.com/UditAkhourii/adhd/issues/18).
  131. - [**A measured duel vs. single-shot**](https://miyagadget.page/en/blog/2026/06/03/adhd-coding-agent-skill-en/) by Shichinomiya ([@shichinomiya_s](https://miyagadget.page)) — 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.
  132. ---
  133. ## License
  134. MIT License.
  135. ADHD operationalizes the *Divergent Ideation* source spec ([SOURCE-SPEC.md](./SOURCE-SPEC.md)). The runnable skill is at [`skills/adhd/SKILL.md`](./skills/adhd/SKILL.md).
  136. ---
  137. ## Contact
  138. **Udit Akhouri** — author of the preprint and maintainer.
  139. [adhdstack.github.io](https://adhdstack.github.io/) · [@akhouriudit](https://x.com/akhouriudit) · [LinkedIn](https://www.linkedin.com/in/udit-akhouri-10160a168/) · [researchudit@gmail.com](mailto:researchudit@gmail.com) · [@UditAkhourii](https://github.com/UditAkhourii)
  140. Open to collaboration with research labs and applied-AI teams working on reasoning, planning, and agentic systems.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.