ADHD: The Open-Source Engine That Stops AI Agents From Falling in Love With the First Idea
A parallel divergence layer for Claude-powered agents that fans out isolated thoughts, scores for traps, clusters by angle, and deepens only the survivors.
- ADHD is less an agent framework than a control system for delaying convergence until ideas have been forced to diverge.
- Its core trick is a hard wall between generation and judgment, which keeps one plausible answer from contaminating the rest of the search space.
- The critic pass is not a simple ranking step, because it looks for traps, clusters by underlying angle, and only then deepens the survivors.
- The project’s real claim is economic as much as technical: expensive reasoning should be spent only after a pre-flight gate says the problem deserves it.
The first idea problem
Most agent workflows do not fail because the model is unimaginative. They fail because the model is too quick to sound right. The first plausible answer becomes the anchor, and every later step quietly bends toward it.
ADHD is built around a blunt objection to that pattern. It treats premature convergence as a systems problem, not a prompt-writing problem. If you want more original answers, you do not just ask harder. You prevent the search from collapsing too early.
What ADHD actually does
The workflow is easy to summarize and hard to get right: fan out isolated branches, score them later, cluster by underlying angle, then deepen only the survivors. That is the whole thesis. Everything else in the repo serves it.
| Approach | How ideas are generated | How evaluation happens | Strength | Failure mode |
|---|---|---|---|---|
| Single-pass agent prompting | One chain produces one answer path | Evaluation is mixed into the same pass | Fast and cheap | Anchors on the first decent idea |
| Standard Tree-of-Thought exploration | Multiple branches explore variants | Branches may still influence one another | Broader search than a single pass | Search can collapse toward similar ideas |
| ADHD hard-wall divergence | Isolated branches think under different frames | A separate critic scores, clusters, and filters | Novelty survives long enough to matter | Costs more compute and latency |
The hard wall between thinking and judging
This is the heart of the project. During divergence, branches are intentionally sealed off from one another. In `src/llm.ts`, that means stateless calls and `allowedTools: []`, which is not a minor implementation detail. It is the point.
Tools create momentum toward solving. Momentum is useful after the search space is open. It is harmful while you are trying to keep the search space from collapsing. ADHD blocks that collapse by making the model generate from a frame, then refusing to let the frame be contaminated by whatever came next.
Frames are the secret sauce
The repo defines 15 cognitive frames, with at least one wild frame required. That is a subtle but important move. The model is pushed out of the obvious lane without being turned loose into randomness.
const FRAMES = [
"speedrunner",
"regulator",
"ten-year-old",
"biology system",
"hardware engineer",
// ...other frames
]
const selection = selectFrames({
tags: ["code", "design"],
requireWild: true,
count: 5,
})
// Divergence uses stateless calls and no tools.
const response = await query({
preset: "claude_code",
allowedTools: [],
prompt: buildFramePrompt(selection)
})We argue ADHD is the right inference-time structure for creative, interdisciplinary, and design-shaped tasks where the failure mode is not wrong but obvious.
Scoring is not ranking
The critic pass is doing more than sorting. It is looking for traps, weighting viability, and clustering by underlying angle instead of keyword similarity. That matters because two ideas can sound different while still belonging to the same mental rut.
The scoring logic in the repo makes that explicit. Novelty is rewarded, viability is weighted most heavily, and fit comes last. That mix says something important: the goal is not just to surprise the model. It is to surprise it without wasting the user's time.
| Dimension | Simple best-of-N | ADHD critic pass |
|---|---|---|
| What gets compared | Surface similarity and overall polish | Novelty, viability, fit, and trap risk |
| What is grouped | Often by wording or immediate shape | By underlying angle |
| What survives | The prettiest answer | The strongest answer that is still structurally honest |
| Main risk | Safe sameness | Higher compute cost |
Why the pre-flight gate matters
The skill interface adds a product judgment layer before the system spends real compute. That is not a footnote. It is the economic guardrail that makes the whole idea credible.
ADHD is more expensive than a normal prompt. The repo is honest about that. The pre-flight gate decides whether the task is fuzzy, architectural, or open-ended enough to justify the extra spend. That makes the tool feel less like a toy and more like infrastructure.
ADHD makes many heads think differently, in parallel, then has a critic pick.
Where ADHD fits in the agent ecosystem
This is not a code generator replacement. It is a planning layer. It fits best when the problem is messy, design-shaped, or interdisciplinary, and when a bad early answer is more dangerous than a slow one.
| Best fit | Why ADHD helps | Why a simpler agent may be enough |
|---|---|---|
| Architecture decisions | Many plausible paths need separation before critique | The task may be too bounded to justify divergence |
| Product strategy | Frames help test different mental models | The answer may already be well-scoped |
| Bug triage with fuzzy symptoms | Isolated branches reduce anchoring on one diagnosis | A direct debugger may be faster |
| Routine code generation | The extra search can be overkill | A single pass is cheaper and sufficient |
What the benchmark does, and what it does not prove
There is a bench folder, a judge loop, and a small evaluation story. That is a good sign. It means the project is trying to measure something real instead of hiding behind vibes.
But the evidence should stay in proportion. The benchmark set is small, so it can suggest a pattern without proving a universal law. The honest read is directional: ADHD may help on creative, open-ended tasks where anchoring is the enemy, but that is not the same as a blanket win.
The interesting signal is not that every score improves. It is that the system makes a choice about when to pay for depth, and then spends that depth where the search process actually benefits from it.
