revanced-adhd

Overview
Install
What changed vs upstream
Before / after
The twelve rules
How it works
Repository layout
Quality checks
Tuning
FAQ
Credits
License

Overview

revanced-adhd shapes agent output so a reader with ADHD (or high executive-function load) can act with less friction.

Follows the Agent Skills format used by the skills CLI.


Install	`npx skills add ChloeVPin/revanced-adhd`
Skill	`skills/revanced-adhd/SKILL.md`
Rules	12 (action-first, four-item chunks, Parked list, …)
Upstream	Fork of ayghri/i-have-adhd
Audit	`AUDIT.md`
Runtime	None - no hooks or background processes

Core idea: next action first · groups of four · visible Parked list · anchored time · default over menu · cause/fix without blame.

Not clinical care. Prompt skill only - not a validated clinical intervention. See limits in AUDIT.md.

Install

Agent Skills CLI (recommended)

Works with Claude Code, Cursor, Codex, and other agents supported by skills:

npx skills add ChloeVPin/revanced-adhd

npx skills add ChloeVPin/revanced-adhd -g              # global
npx skills add ChloeVPin/revanced-adhd --list          # list only
npx skills add ChloeVPin/revanced-adhd --skill revanced-adhd -y   # non-interactive
npx skills update revanced-adhd                        # later

Listing on skills.sh/ChloeVPin/revanced-adhd comes from install telemetry - no separate publish form.

Claude Code plugin (optional slash command)

git clone https://github.com/ChloeVPin/revanced-adhd ./revanced-adhd
claude plugin marketplace add ./revanced-adhd
claude plugin install revanced-adhd@revanced-adhd

/revanced-adhd

Stop with stop adhd mode or normal mode. Full guide: INSTALL.md.

What changed vs upstream

Full rationale: AUDIT.md · Release notes: CHANGELOG.md

Original rule	Gap	What `revanced-adhd` does
Cap lists at 5	5 is closer to Miller’s 7 than to Cowan’s ~4-chunk limit	Cap at 4 for lists and numbered steps
“Save it for later”	Side topic is not externalized; it is lost on topic change	Persistent, visible Parked list
One attention mode	No hyperfocus handling	Rule 12: reduce structure during rapid, self-directed work
“Matter-of-fact” errors	Bans tone, not blame words	Ban “you forgot” / “your mistake”; cause lives in the system
Numeric time only	Numbers alone do not fix time blindness	Number plus reference activity
Neutral menus	Unranked choice is a new task	Named Default with one-line reason

Engineering fixes (not ADHD research):

Ships a real commands/revanced-adhd.md (upstream README referred to a missing command file).
Ships lint script, fixtures, and CI workflow.

flowchart TB
  subgraph upstream["ayghri/i-have-adhd"]
    U1[10 rules]
    U2[Prompt only]
  end

  subgraph audit["AUDIT.md"]
    A1[6 research gaps]
    A2[2 doc / tooling gaps]
  end

  subgraph fork["revanced-adhd"]
    F1[12 rules]
    F2[Parked list]
    F3[Hyperfocus rule]
    F4[lint_output.py + CI]
    F5[Real slash command]
  end

  upstream --> audit --> fork

Before / after

Before (typical LLM output)	After (`revanced-adhd`)
Great question! Let me think about this. Your auth flow has a few moving pieces. You could use Postgres for sessions, or MySQL, or SQLite. By the way, your dependency is also a bit out of date. Hope this helps!	Run `npm install jsonwebtoken@latest`, then edit `src/auth.ts:42`.
Answer buried under preamble	First line = action
Flat menu of options	Default: Postgres + short reason
Side note disappears	Parked: dependency flagged
Soft closer, no next step	Next: paste first failing test line

Example shaped reply

Run `npm install jsonwebtoken@latest`, then edit `src/auth.ts:42`.

**[Step 1/3]**
1. Open `src/auth.ts`
2. Replace `verifyToken` (lines 42-58) with the snippet below
3. Run `npm test -- auth.spec.ts`

**Default: Postgres** - you already run it in other places.
Alternatives: SQLite (simpler, no server) or MySQL (only if a team rule requires it).

**Parked:** `jsonwebtoken` is two majors behind (flagged, not upgraded).

Next: paste the first failing line if a test fails.

Live fixtures used by CI:

The twelve rules

Full text and “why” for each rule: skills/revanced-adhd/SKILL.md.

#	Rule	One-line intent
1	Lead with the next action	First line is doable (command, path, snippet, or decision)
2	Chunk multi-step work to four	Phases for the rest; expand current phase only
3	End with exactly one next action	Concrete, under ~2 minutes
4	Park tangents visibly	Running Parked list; append, do not drop
5	Restate state each turn	Parseable `[Step X/Y]` tag
6	Anchor time estimates	Number + known activity (e.g. one coffee break)
7	Separate wins from what’s next	Two lines, two jobs
8	Depersonalize errors	Cause and fix; never blame the reader
9	Default, don’t menu	Name a default before alternatives
10	Cap any list at four	Split must / later if needed
11	No preamble / recap / closers	Start with the answer; stop when done
12	Back off during hyperfocus	Drop scaffolding when the user is mid-flow

Override paths

flowchart TD
  Start[Incoming user message] --> HF{Last 2+ turns rapid,<br/>technical, self-directed?}
  HF -->|yes| Slim[Rule 12: minimal scaffolding]
  HF -->|no| Full[Apply rules 1-11]
  Slim --> OVR
  Full --> OVR{Override case?}
  OVR -->|Explain / walk through| Long[Full length; still no preamble/closer]
  OVR -->|Destructive action| Confirm[Confirm before act]
  OVR -->|Debug spiral 3x| Ask[Name assumption; one diagnostic Q]
  OVR -->|Real ambiguity| Clarify[One short clarifying Q]
  OVR -->|None| Out[Normal shaped reply]
  Long --> Out
  Confirm --> Out
  Ask --> Out
  Clarify --> Out

Six facts behind the rules

Working memory holds about four chunks (Cowan 2001), not seven.
Knowing the answer is not doing the answer - first line must be an action.
Subjective time is flat; bare numbers under-fix time blindness.
Deferred info that is not externalized is lost, not postponed.
Open menus without a default raise choice load.
Perceived blame lands harder; put the fault in the system, not the reader.

Sources and caveats: AUDIT.md.

How it works

No hooks. No background processes. Same “zero magic” design as upstream.

Via npx skills: installs skills/revanced-adhd/ into agent skill dirs. The agent loads it when the description matches.

Via Claude plugin: /revanced-adhd applies the same rules for the session until stop adhd mode / normal mode.

flowchart LR
  A["npx skills add"] --> B["Agent skill dirs"]
  B --> C["Load SKILL.md when relevant"]
  D["/revanced-adhd plugin"] --> C
  C --> E["Action-first replies"]

Repository layout

revanced-adhd/
├── skills/revanced-adhd/SKILL.md   # Agent Skills payload (required)
├── .claude-plugin/                 # Optional Claude Code marketplace
├── commands/revanced-adhd.md       # Optional /revanced-adhd
├── scripts/lint_output.py          # Maintainer QA (not runtime)
├── tests/                          # Fixtures + manual cases
├── docs/assets/                    # Logo
├── AUDIT.md · CHANGELOG.md · INSTALL.md · LICENSE
└── README.md

Path	Installed by `npx skills`?
`skills/revanced-adhd/`	Yes
Docs, plugin, lint, tests	No - repo only

Quality checks

What the linter covers

Checkable in one message	Needs multi-turn history
Preamble / closers	Parked list persistence
Blame language	`[Step X/Y]` restatement
List length (>4 without split)	Hyperfocus (rule 12)
Menu without default
Vague time estimates
Action-first first line (heuristic WARN)

Manual multi-turn cases: tests/cases.md.

Run locally

# Single response
python3 scripts/lint_output.py path/to/a/response.md

# Strict: WARN also fails
python3 scripts/lint_output.py --strict path/to/a/response.md

# Fixture suite (same as CI)
bash tests/run_lint_tests.sh

CI pipeline

flowchart LR
  Push[push / pull_request] --> CO[actions/checkout]
  CO --> PY[setup-python 3.x]
  PY --> T[bash tests/run_lint_tests.sh]
  T --> G[good fixture → exit 0]
  T --> B[bad fixture → exit 1]
  G --> OK[Job green]
  B --> OK

Workflow: .github/workflows/lint.yml.

The linter is a heuristic smoke test, not proof of full skill compliance. See limits in AUDIT.md.

Tuning

Edit skills/revanced-adhd/SKILL.md.
Re-invoke /revanced-adhd (or start a new session).
If you change a linted rule, run:

bash tests/run_lint_tests.sh

For multi-turn behavior, walk through tests/cases.md.

FAQ

Is this only “be terse”?
No. Twelve rules tied to working memory, time sense, and choice load - sources in AUDIT.md.

Does it break long explanations?
No. Override: “explain” / “walk me through” may use full length. Still no preamble or closer.

Is this clinically validated?
No. Read limits in AUDIT.md.

Do I need a diagnosis?
No.

Does the lint script run during chat?
No. Maintainer QA only.

skills.sh listing?
Public repo + npx skills add telemetry. Guide: Vercel agent skills.

Credits

Forked from ayghri/i-have-adhd by Ayoub Ghriss (MIT).

Upstream started from ten rules and a frame loosely based on The Adult ADHD Tool Kit. This fork’s changes come from auditing that frame against:

Cowan’s working-memory research
Barkley and Sonuga-Barke on time perception in ADHD
Dodson’s clinical writing on rejection sensitivity

Details and caveats: AUDIT.md.

License

MIT. Original copyright retained. Fork modifications have a separate copyright line.

Revanced Adhd

README