ADHD: Parallel Divergent Thinking Skill for Coding Agents
Tree-of-thought with pruning: spawns isolated reasoning processes under cognitive frames to fight premature convergence.
- Source repo
- UditAkhourii/adhd
- Stars
- ★ 4.4k
- Last updated
- 13d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 56/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- When designing a rate limiter, use ADHD to explore diverse strategies, such as scout-forking alternate endpoints or daemonizing the CLI.
- Not a fit if
- Simple, straightforward tasks where one answer suffices
- Teams sensitive to API cost and latency: ~2.3× time, 1.9× output
- Source review
- 56/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
ADHD is a skill for coding agents designed to structurally address premature convergence in autoregressive reasoning. Unlike linear chain-of-thought or tree-of-thought, which share a single context and thus preserve anchoring, ADHD spawns N parallel, isolated reasoning processes under deliberately distorted cognitive frames with zero shared context during divergence. A separate critic pass then scores, clusters, prunes traps, and deepens the survivors. It provides a two-phase loop (Diverge and Focus), with the generator-critic split enforced as separate LLM calls with opposite system prompts. The package ships a CLI (adhd), a TypeScript library (adhd-agent) exposing run() and renderText(), and a skill for agents (SKILL.md) installable via npx skills add. Benchmarks show ADHD outperforms a single-shot baseline in breadth, novelty, trap detection, and actionability, with particularly strong gains in trap detection (9.5 vs 1.8). Adopted by projects like repowire, mstack, and han. Maintained by Udit Akhouri with a preprint and detailed documentation.
ADHD executes a two-phase loop. In the Diverge phase, it selects N cognitive frames based on the problem, spawns N parallel agent calls—each seeing the problem plus a frame's vantage prompt, with a system prompt forbidding evaluation—so branches never see each other. In the Focus phase, a separate critic LLM call scores every idea on novelty, viability, and fit, flags traps with reasons, clusters ideas by underlying angle, and deepens the top-K survivors into sketches with risks and first steps. The library API returns structured results including shortlist, nonObviousPick, traps, deepened, and clusters. It reads user problems from CLI arguments or API parameters, calls the configured LLM provider (Claude or Codex), and outputs rendered text or JSON. The skill integrates into agent environments like Claude Code and Codex, auto-triggering on ideation intents or via /adhd commands. It does not execute code but provides ideation suggestions.
- When designing a rate limiter, use ADHD to explore diverse strategies, such as scout-forking alternate endpoints or daemonizing the CLI.
- When debugging a fuzzy issue, like an LLM CLI hanging for 90 seconds, ADHD surface non-obvious picks like 'rage-quit' to instantly switch to a cheaper model.
- When naming functions or APIs, run ADHD to generate creative suggestions across different cognitive frames.
- When planning architecture or strategy, use ADHD to consider multiple perspectives and avoid settling on the first idea.
- When reviewing ideas for pitfalls, ADHD's focus phase automatically flags traps with reasons, saving engineering time.
- When building other agent skills, incorporate ADHD's generator-critic split pattern into your own workflows, as done by repowire and mstack.
How do you install or deploy this agent?
Requires Node.js >=18. Install the CLI globally: npm install -g adhd-agent. Or as a library in a project: npm install adhd-agent. For agent integration, the recommended path is: npx skills add UditAkhourii/adhd, which auto-detects ~50 agents (Claude Code, Cursor, Antigravity, Codex, etc.). If Codex fails to auto-detect, force the target: npx skills add UditAkhourii/adhd -a codex -g. Manual install for Codex: mkdir -p ~/.codex/skills/adhd; curl -fsSL https://raw.githubusercontent.com/UditAkhourii/adhd/main/skills/adhd/SKILL.md -o ~/.codex/skills/adhd/SKILL.md, then restart Codex.
How do you use this agent?
From CLI: run adhd "your problem" (e.g., adhd "design a rate limiter"). Options include --frames, --ideas, --top for tuning. From TypeScript: import { run, renderText } from 'adhd-agent'; const result = await run({ problem: '...', framesPerRun: 5, topK: 3 }); console.log(renderText(result));. In agent environments, invoke /adhd "your problem" or let it auto-trigger on ideation intents. The skill ships with a single-line description to ensure compatibility with Codex builds.
What are this agent's strengths and limitations?
- Significant improvement in idea breadth (9.0 vs 4.8) and novelty (7.8 vs 2.7) over single-shot baselines in independent evals.
- Excellent trap detection (9.5 vs 1.8), automatically flagging seductive-but-broken ideas with reasons.
- Flexible integration: CLI, library, and skill for ~50 agents, with one-command installation.
- Methodologically grounded with a preprint, detailed documentation, and community adoption (repowire, mstack, etc.).
- Structured output (shortlist, nonObviousPick, traps) makes it easy to integrate into other pipelines.
- Higher resource consumption: about 2.3× time and 1.9× output compared to single-shot, increasing LLM API costs.
- Requires network access and API credentials to operate; cannot run fully offline.
- Full one-command install may not work on all agents; Codex sometimes needs manual configuration.
- May be overkill for simple, straightforward tasks where a single answer suffices.
- Potential for the critic to miss certain structured reasoning patterns, though docs claim generality; not all ideas may be actionable.
How does this agent compare with similar options?
Compared to standard chain-of-thought and tree-of-thought methods, ADHD's key differences are isolated divergence (no shared context) and a mechanical generator-critic split via separate LLM calls. It is not compared to other specific tools in the source.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| ADHD: Parallel Divergent Thinking Skill for Coding Agents This agent | 56 · Major gaps | Agent plugin / skillFree + model costs | ★ 4.4k | 13d ago | TypeScript | Codex · Claude Code |
| AgentBridge | 61 · Some gaps | CLIFree + model costs | ★ 402 | 1mo ago | TypeScript | Codex · Claude Code |
| OpenCove Infinite Canvas Workspace | 46 · Major gaps | Desktop appFree | ★ 1.6k | 2d ago | TypeScript | Codex · Claude Code |
| img2threejs — Code-Only 3D Reconstruction | 45 · Major gaps | Agent plugin / skillFree + model costs | ★ 18k | 11d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: generation-only queries disable all built-in tools (tests/llm.test.ts), aligning with least privilege; but user confirmation mechanism not explicit, data flow transparency limited, sensitive data handling not specified, dependency security not audited, external effects (e.g., network calls) not clarified, rollback missing, source attribution has MIT attribution but unverified. Deductions: insufficient evidence for user confirmation, data flow, sensitive data, dependency security, external effects, rollback.
Evidence: README and code consistent, dependencies pinned (package.json), CI covers multiple Node versions; but failure messages not detailed. Deduction: insufficient evidence for failure messages.
Evidence: clear target audience (coding agents) and scenarios (design decisions, fuzzy debugging, etc.), capability boundaries documented (when-to-use), trigger explicit (/adhd), environment fit broad (multiple agents). Deductions: no major flaws, but some details unverified.
Evidence: clear documentation structure (README, documentation/), detailed install notes, stable naming (adhd-agent), rich examples, known limitations documented, MIT license, version number exists but no changelog, maintenance responsibility clear (author). Deduction: no changelog.
Evidence: clear output structure (shortlist, traps, etc.), marginal value supported by comparative data, cost-benefit discussed (time/output cost). Deductions: no major flaws, but cost data relies on external evals.
Evidence: claims supported by docs (evals.md), external evals cross-corroborate, facts and inferences separated (methodology explicit). Deductions: no major flaws.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Publisher identity unverified; source attribution based solely on MIT claim.
- Dependency security not audited; recommend checking for vulnerabilities.
- User confirmation mechanism unclear; may execute actions automatically.
- Rollback mechanism absent; changes may be hard to revert.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.1.4 v0.1.4 — Community is open · Codex compatibility · first OSS adopter
Release notes excerpt
🎉 The ADHD community is open If you build with coding agents, sign up at https://tally.so/r/WO1Nzj as a contributor, maintainer, early adopter, or just a member who wants to follow along. Full discussion: https://github.com/UditAkhourii/adhd/discussions/19 Where we are - 5/6 wins vs a single-shot baseline across 6 open-ended engineering problems, with +5.17 novelty and +7.67 trap detection on a 0–10 rubric — full methodology in [EVALS.md](https://github.com/UditAkhourii/adhd/blob/main/EVALS.md). …View on GitHub ↗