{"id":50754718,"url":"https://github.com/UditAkhourii/adhd","last_synced_at":"2026-06-11T21:00:47.217Z","repository":{"id":360238740,"uuid":"1249107749","full_name":"UditAkhourii/adhd","owner":"UditAkhourii","description":"ADHD — a skill for coding agents. Tree-of-thought with pruning, built on the Claude 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.","archived":false,"fork":false,"pushed_at":"2026-05-25T15:30:21.000Z","size":187,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T02:39:04.987Z","etag":null,"topics":["adhd","agents","ai","ai-agents","brainstorm","chain-of-thought","claude","claude-agent-sdk","creativity","divergent-thinking","ideation","interdisciplinary","llm","llm-tools","nodejs","prompt-engineering","tree-of-thought","typescript"],"latest_commit_sha":null,"homepage":"https://uditakhourii.github.io/adhd/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UditAkhourii.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T11:06:35.000Z","updated_at":"2026-05-25T15:30:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/UditAkhourii/adhd","commit_stats":null,"previous_names":["uditakhourii/adhd"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/UditAkhourii/adhd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UditAkhourii%2Fadhd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UditAkhourii%2Fadhd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UditAkhourii%2Fadhd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UditAkhourii%2Fadhd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UditAkhourii","download_url":"https://codeload.github.com/UditAkhourii/adhd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UditAkhourii%2Fadhd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34217312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adhd","agents","ai","ai-agents","brainstorm","chain-of-thought","claude","claude-agent-sdk","creativity","divergent-thinking","ideation","interdisciplinary","llm","llm-tools","nodejs","prompt-engineering","tree-of-thought","typescript"],"created_at":"2026-06-11T04:00:27.564Z","updated_at":"2026-06-11T21:00:47.170Z","avatar_url":"https://github.com/UditAkhourii.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","🧠 Agent Skills","⭐ 精选第三方技能","Coding and Refactoring Skills"],"sub_categories":["💻 开发效率"],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://adhdstack.github.io/\"\u003e\n    \u003cimg src=\"docs/hero.png\" alt=\"ADHD for Claude Code\" width=\"100%\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# ADHD — a skill for agents\n\n[![CI](https://github.com/UditAkhourii/adhd/actions/workflows/ci.yml/badge.svg)](https://github.com/UditAkhourii/adhd/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/adhd-agent.svg)](https://www.npmjs.com/package/adhd-agent)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](./documentation/install.md)\n[![Paper](https://img.shields.io/badge/paper-preprint-blueviolet)](https://adhdstack.github.io/)\n[![Featured: The New Stack](https://img.shields.io/badge/featured-The%20New%20Stack-ff5500)](https://thenewstack.io/claude-code-adhd/)\n\n\u003e **An architectural fix for premature convergence in autoregressive reasoning.**\n\nLinear 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.\n\nReach for it on **design decisions, fuzzy debugging, naming, API surface design, strategy, and any prompt of the shape *\"give me a few ways to…\"***.\n\n📄 **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/)\n\n---\n\n## Side-by-side: baseline vs ADHD\n\nOne eval problem, same model, two strategies. Full transcripts in [`bench/results.json`](./bench/results.json).\n\n\u003e **Problem.** *\"We have a CLI that calls an LLM and it sometimes hangs for 90 seconds. Design the right retry/timeout/UX strategy.\"*\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth width=\"50%\"\u003e🟦 Baseline (single-shot)\u003c/th\u003e\n\u003cth width=\"50%\"\u003e🟧 ADHD\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr valign=\"top\"\u003e\n\u003ctd\u003e\n\nWalks through four **textbook** patterns:\n\n1. Progressive timeout with staged UI (10s / 30s / 60s)\n2. Fast-fail + exponential backoff retry\n3. Hedged parallel requests\n4. Streaming with keepalive\n\nLands 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.\n\n**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.\n\n\u003c/td\u003e\n\u003ctd\u003e\n\nSpawns 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:\n\n- ★ **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.**\n- Plus shortlist: scout-fork to alternate endpoints at 30s; daemonize the CLI with ticket IDs; race 3 LLM replicas, cache the winner.\n- **20 traps flagged with one-line reasons** — including the cute \"stream tokens in reverse\" and \"patience-token billing\" ideas before they cost engineering time.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nIndependent 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).\n\n---\n\n## Featured\n\n- 🔌 **Adopted by [repowire](https://github.com/prassanna-ravishankar/repowire)** — the first OSS project to officially ship ADHD. Its maintainer ported the framework onto repowire's mesh-orchestrator primitives in [PR #313](https://github.com/prassanna-ravishankar/repowire/pull/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).\n- 📰 **[The New Stack](https://thenewstack.io/claude-code-adhd/)** ran a feature story on ADHD for Claude Code.\n- 💬 **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.\"*\n- 🔬 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).\n\n---\n\n## Community\n\n👉 [**Join the ADHD community →**](https://tally.so/r/WO1Nzj) as a contributor, maintainer, early adopter, or just a member. One short form. We coordinate frame contributions, eval problems, integrations, and adopter onboarding there.\n\n---\n\n## Early adopters\n\nProjects that officially ship or integrate ADHD:\n\n| Project | What they did | Status |\n|---|---|---|\n| [**repowire**](https://github.com/prassanna-ravishankar/repowire) | Ported 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](https://github.com/prassanna-ravishankar/repowire/pull/313)) | ✅ Merged · MIT attribution |\n| [**mstack**](https://github.com/mayank-io/mstack) | Vendored 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 |\n| [**zk-flow-oss**](https://github.com/matt-metivier/zk-flow-oss) | Adapted ADHD's `IDEATION_FRAMES` into their critique workflow ([`src/workflows/critique.src.js`](https://github.com/matt-metivier/zk-flow-oss/blob/main/src/workflows/critique.src.js)) as a pre-pass to reduce anchoring bias before review. | ✅ Shipped · MIT attribution |\n| [**han**](https://github.com/testdouble/han) | Published an [evidence-based research application](https://github.com/testdouble/han/blob/adhd-swarm-research/docs/research/adhd-application-to-han.md) of ADHD onto Han's plugin model — 11 sources, 8 validation rounds. Findings landed as issues [#16](https://github.com/UditAkhourii/adhd/issues/16)–[#18](https://github.com/UditAkhourii/adhd/issues/18). | ✅ Research integration |\n| [**app-library** (yslee5005)](https://github.com/yslee5005/app-library) | Built an `expert-thinker` MoAI agent on the ADHD pattern — tree-of-thought with isolated divergence and a separate critic pass. | ✅ Shipped |\n| [**striatum**](https://github.com/halbritt/striatum) | Installer scaffold for Claude Code recommends `npx skills add UditAkhourii/adhd` for architecture, API design, and naming work. | ✅ Shipped |\n| [**awesome-prompts**](https://github.com/ai-boost/awesome-prompts) | Packaged the ADHD loop as a standalone prompt (`adhd_parallel_ideation_skill.txt`) for users without the skill installed. | ✅ Shipped |\n| [**nix-skills**](https://github.com/sudosubin/nix-skills) | Nix packaging of the ADHD skill (pinned to commit `770834e`) for the Nix-based agent-skills ecosystem. | ✅ Shipped |\n| [**caioniehues/adhd**](https://github.com/caioniehues/adhd) | Fork with a customized `SKILL.md` that re-points install + docs to their own distribution while keeping upstream attribution. | ✅ Fork · attribution |\n| [**ktg-one/adhd**](https://github.com/ktg-one/adhd) | Fork used as a personal \"codified model of how my brain works\" — wired into the [may-2026-kb](https://github.com/ktg-one/may-2026-kb) knowledge base as a cognitive-architecture pattern. | ✅ Fork · in use |\n\nShipping ADHD in your project? Open a PR adding it here, or [open an issue](https://github.com/UditAkhourii/adhd/issues/new) and we'll add you.\n\n---\n\n## Install\n\nOne command, auto-detects your agent (Claude Code, Cursor, Antigravity, Codex, Cline, Gemini CLI, Windsurf, and ~50 more):\n\n```bash\nnpx skills add UditAkhourii/adhd\n```\n\nThen invoke explicitly with `/adhd \"your problem\"`, or let it auto-trigger on ideation intents.\n\n### Codex quick path\n\nIf the universal command above fails to register inside Codex (some Codex builds discover skills from a specific path), force the target:\n\n```bash\nnpx skills add UditAkhourii/adhd -a codex -g\n```\n\nOr install manually into Codex's skills directory:\n\n```bash\nmkdir -p ~/.codex/skills/adhd\ncurl -fsSL https://raw.githubusercontent.com/UditAkhourii/adhd/main/skills/adhd/SKILL.md \\\n  -o ~/.codex/skills/adhd/SKILL.md\n```\n\nRestart 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.\n\nCLI and library installs, manual curl for other agents, and per-platform paths are in **[documentation/install.md](./documentation/install.md)**.\n\n```bash\nnpm install -g adhd-agent     # CLI\nnpm install adhd-agent        # library\n```\n\n---\n\n## Quickstart\n\n```bash\nadhd \"design a rate limiter that survives a leader election\"\nadhd \"name this function\" --frames 3 --ideas 8 --top 2\n```\n\n```ts\nimport { run, renderText } from \"adhd-agent\";\n\nconst result = await run({ problem: \"How should we shard this queue under bursty load?\", framesPerRun: 5, topK: 3 });\nconsole.log(renderText(result));\n// result.shortlist · result.nonObviousPick · result.traps · result.deepened · result.clusters\n```\n\nFull reference: **[documentation/api.md](./documentation/api.md)**.\n\n---\n\n## How it works\n\nA two-phase loop with a hard wall between the phases.\n\n1. **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.\n2. **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.\n\nThe 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)**.\n\n---\n\n## Results\n\nMean 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.\n\n| Dimension          | ADHD     | Baseline | Δ         | Ratio |\n| ------------------ | -------: | -------: | --------: | ----: |\n| breadth            | **9.00** | 4.83     | **+4.17** | 1.9×  |\n| novelty            | **7.83** | 2.67     | **+5.17** | 2.9×  |\n| trap detection     | **9.50** | 1.83     | **+7.67** | 5.2×  |\n| actionability      | **9.50** | 6.50     | **+3.00** | 1.5×  |\n| builder usefulness | **7.67** | 6.83     | **+0.83** | 1.1×  |\n\n**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)**.\n\n---\n\n## Documentation\n\n| Page | What's in it |\n|---|---|\n| [Install](./documentation/install.md) | Every install path — skill, CLI, library, Agent SDK, per-platform |\n| [How it works](./documentation/how-it-works.md) | The two-phase loop + architecture (context, pruning, orchestration) |\n| [vs CoT \u0026 ToT](./documentation/vs-cot-and-tot.md) | Structural comparison, the three load-bearing differences, frames vs personas |\n| [Frames](./documentation/frames.md) | The 15 cognitive frames, how selection works, how to author your own |\n| [When to use](./documentation/when-to-use.md) | Use / don't use, why it shines on creative work, cost \u0026 speed |\n| [CLI \u0026 API](./documentation/api.md) | CLI flags, library types, using ADHD inside your own agent |\n| [Evals](./documentation/evals.md) | Methodology, headline numbers, limitations, roadmap |\n\nAlso: [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/).\n\n---\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=uditakhourii%2Fadhd\u0026type=date\u0026legend=top-left\"\u003e\n  \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=uditakhourii/adhd\u0026type=date\u0026legend=top-left\" style=\"background:#ffffff\" /\u003e\n\u003c/a\u003e\n\n---\n\n## External reviews\n\n- [**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).\n\n---\n\n## License\n\nMIT License.\n\nADHD 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).\n\n---\n\n## Contact\n\n**Udit Akhouri** — author of the preprint and maintainer.\n\n[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)\n\nOpen to collaboration with research labs and applied-AI teams working on reasoning, planning, and agentic systems.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUditAkhourii%2Fadhd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FUditAkhourii%2Fadhd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUditAkhourii%2Fadhd/lists"}