ADHD: A Two-Phase Ideation Skill for Coding Agents
UditAkhourii/adhd
ADHD is a skill for coding agents that runs N isolated LLM calls, each locked to a different cognitive frame, then a separate critic pass that scores, prunes, and deepens the survivors. Reach for it on fuzzy, open-ended problems — naming, API design, debugging strategy. Skip it when there's one correct answer, where firing 6+ parallel calls just burns tokens for no gain.
Addressing Premature Convergence in LLMs
Linear Chain-of-Thought commits to whatever it states first, and Tree-of-Thought's branches still share one context, so the same anchoring persists across the tree — that's the specific failure mode ADHD's README targets. Widening the search alone doesn't fix it if every branch can still see what the others already said. The gap is a missing hard wall between generation and evaluation, not a lack of prompting cleverness, and that's the piece ADHD adds.
Understanding ADHD's Two-Phase Reasoning
ADHD is an open-source skill built on the Claude and Codex Agent SDK that treats premature convergence in LLM reasoning as an architecture problem, not a prompting one. It runs N parallel, isolated Agent calls under different cognitive frames — zero shared context, so nothing anchors — then a separate critic call scores, flags traps, clusters, and deepens the top ideas.
Core Capabilities for Agent Creativity
- ✓Diverge phase spawns N parallel Agent calls, each locked to one cognitive frame with a system prompt that forbids evaluation — branches share zero context, so nothing anchors on an earlier branch's answer.
- ✓Focus phase runs a separate critic call that scores every idea on novelty, viability, and fit, per the README.
- ✓Critic flags traps — ideas that look promising but aren't — with a one-line reason for each, then clusters ideas by underlying angle.
- ✓Deepens the top-K survivors into sketches that include risks and first steps, not just a shortlist.
- ✓Ships with 15 cognitive frames (documentation/frames.md), plus a documented path to author your own.
- ✓TypeScript API exposes structured fields — result.shortlist, result.nonObviousPick, result.traps, result.deepened, result.clusters — instead of a single text blob.
- ✓CLI flags --frames, --ideas, and --top control fan-out width and shortlist size directly.
When to Apply ADHD for Problem Solving
- •Design decisions, fuzzy debugging, naming, and API surface design — the four cases the README names directly.
- •Any prompt shaped 'give me a few ways to...' where a single-shot answer would just restate the obvious pattern.
- •The README's own worked example: a CLI retry/timeout/UX strategy problem, where ADHD's 6 isolated frames surfaced 30+ ideas and flagged 20 traps versus the baseline's four textbook patterns.
- •Codebase onboarding: the adopter wtfismyrepo runs the diverge-score-cluster-deepen loop over 12 codebase-specific frames — reading the code as a new grad might, then as an archaeologist, a security researcher, the engineer on call at 3am, a refactorer, and more — to surface onboarding angles.
- •Architecture review passes involved adopter mythify, where trap-clause guidance was added to its analysis prompt. This occurred after ADHD's pattern had been evaluated, with the aim of surfacing 'the one appearing positive but proving negative, and the reasons for this outcome' before a plan ships.
Installing ADHD into Your Agent
One command installs the skill and auto-detects your agent: `npx skills add UditAkhourii/adhd` — the README lists Claude Code, Cursor, Antigravity, Codex, Cline, Gemini CLI, Windsurf, and about 50 more as supported targets. After install, invoke it explicitly with `/adhd "your problem"`, or let it auto-trigger on ideation-shaped prompts. If the universal installer doesn't register inside Codex, force the target with `npx skills add UditAkhourii/adhd -a codex -g`, or install manually: `mkdir -p ~/.codex/skills/adhd` then curl SKILL.md from the repo's raw GitHub URL into that folder and restart Codex. For CLI or library use instead of the agent skill: `npm install -g adhd-agent` (CLI) or `npm install adhd-agent` (library).
Quickstart with CLI and TypeScript
The CLI takes a problem string directly: `adhd "design a rate limiter that survives a leader election"`, or with flags: `adhd "name this function" --frames 3 --ideas 8 --top 2` to set frame count, ideas per frame, and shortlist size. The TypeScript API is `import { run, renderText } from "adhd-agent"`, then `const result = await run({ problem: "How should we shard this queue under bursty load?", framesPerRun: 5, topK: 3 })` followed by `console.log(renderText(result))`. The result object exposes result.shortlist, result.nonObviousPick, result.traps, result.deepened, and result.clusters as separate fields you can consume programmatically. Full flag and type reference sits in documentation/api.md.
Performance Gains in Breadth and Novelty
- ✓Breadth 9.00 vs a single-shot baseline's 4.83 (+4.17, 1.9×) across the README's 6-problem benchmark.
- ✓Trap detection 9.50 vs 1.83 (+7.67, 5.2×) — the widest gap in the whole results table, and the one the README calls out as the headline finding.
- ✓Novelty 7.83 vs 2.67 (+5.17, 2.9×), with actionability also ahead at 9.50 vs 6.50 (+3.00, 1.5×), so deepened picks come with risks and first steps attached.
- ✓An outside benchmark run by Shichinomiya reproduced the pattern independently on 2 problems: novelty rose from 4.5 to 9.0 and trap detection from 5.0 to 9.0.
- ✓The generator-critic split is mechanical — two separate LLM calls with opposing system prompts — not something asked for inside a single prompt, which the README argues is why the anchoring problem actually goes away.
Considerations for Using ADHD
- △The same independent benchmark that confirms the novelty and trap-detection gains also clocks the real cost: about 2.3× the time and 1.9× the output of a single-shot run.
- △The headline Results table is 6 open-ended engineering problems scored by one LLM judge with randomized A/B order — a useful signal, not a large-scale study.
- △It fires N parallel Agent SDK calls before producing a single idea, so it's a poor fit for anything with one correct answer or a tight latency budget.
- △Codex support needs a manual fallback (mkdir + curl into ~/.codex/skills/adhd/) because the universal npx skills add installer doesn't always register there.
ADHD Compared to CoT and ToT
Frequently Asked Questions
ADHD is released under the MIT License, per the GitHub repository.
Tree-of-Thought widens the search into branches but keeps them in one shared context, so per ADHD's README the same anchoring persists across the tree. ADHD instead spawns fully isolated diverge calls with zero shared context, then runs a separate critic call to score, prune, and deepen — a mechanical generator-critic split rather than a wider single prompt.
ADHD's README points it at design decisions, fuzzy debugging, naming, API surface design, strategy, and any prompt shaped 'give me a few ways to...' — not problems with one correct answer.
ADHD's installer auto-detects around 50 agents, including Cursor, Antigravity, Codex, Cline, Gemini CLI, and Windsurf, not just Claude Code, according to the README.
The README's own 6-problem benchmark shows ADHD ahead on breadth (9.00 vs 4.83), novelty (7.83 vs 2.67), and trap detection (9.50 vs 1.83) against a single-shot baseline, but an independent tester measured roughly 2.3× the time and 1.9× the output of a single-shot run.
The README's documentation/frames.md explains how frame selection works and how to author new ones, and a linked community form coordinates frame contributions from adopters.
Who should try it — and who should skip
Reach for ADHD if you're already running Claude Code, Codex, or another Agent SDK-compatible CLI and you hit fuzzy, open-ended problems often enough that a 1.9x-to-2.3x time cost per run is worth it for a wider idea set and named traps. Skip it if your problems have one correct answer, if you're latency- or budget-constrained, or if you want a lighter single-prompt technique — Chain-of-Thought or a plain Tree-of-Thought prompt costs one call, not N-plus-a-critic.
Related repositories
Curious whether adhd is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about adhd.