Skip to content
Back to search

adhd-study-coach

ADHD-friendly study companion agent for Claude Code: spaced repetition, small-chunk teaching, Feynman reflection

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/itsaalaa7--adhd-study-coach/badge.svg)](/listings/itsaalaa7--adhd-study-coach)

HTML

<a href="/listings/itsaalaa7--adhd-study-coach"><img src="/api/listings/itsaalaa7--adhd-study-coach/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "adhd-study-coach-marketplace",
  3. "description": "Marketplace for the ADHD Study Coach plugin — a single, science-grounded study-companion agent for ADHD learners in any subject.",
  4. "owner": {
  5. "name": "Aalaa Fahiem"
  6. },
  7. "plugins": [
  8. {
  9. "name": "adhd-study-coach",
  10. "source": "./",
  11. "description": "A single study-companion agent for ADHD learners, any subject — automatic spaced-repetition warm-ups, small-chunk teaching, Feynman-style reflection, and periodic self-analysis.",
  12. "version": "0.2.0"
  13. }
  14. ]
  15. }
README.md · README · 206 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🧠 ADHD Study Coach
  2. **An AI study coach for people with ADHD. Works for any subject, in ChatGPT, Gemini, Claude and more.**
  3. > It quizzes you on old stuff, teaches new stuff in tiny pieces, and makes you explain it back. You never have to remember to ask for review.
  4. ---
  5. ## ⚡ Start here (no tech skills needed)
  6. **1. Copy the coach.** Go to the [**website**](https://itsaalaa7.github.io/adhd-study-coach/) and press the big **Copy** button. (No button? Open [this page](https://raw.githubusercontent.com/itsAalaa7/adhd-study-coach/main/universal/adhd-study-coach-compact.md), press `Ctrl+A` then `Ctrl+C`; Mac: `Cmd+A`, `Cmd+C`.)
  7. **2. Paste it into a new chat** in the AI you already use (ChatGPT, Gemini, Claude, Copilot, anything) and press send.
  8. **3. Type `new`,** then tell it what you want to learn. Example: `let's study photosynthesis`.
  9. That's it. It asks 3 quick questions the first time, then you're studying.
  10. ### 💾 Coming back the next day
  11. Chats forget. So at the end of each session the coach gives you a small block of text called a **Progress Card**.
  12. - **Save it** anywhere (Notes app, a document, email to yourself).
  13. - **Paste it** at the start of your next chat, after the coach.
  14. That's how it knows what to quiz you on.
  15. > Want it set up permanently? See [setup for each app](./universal/README.md): ChatGPT, Gemini, Claude, OpenCode, Command Code, OpenRouter.
  16. ---
  17. ## 🛠️ For Claude Code users
  18. Progress saves **automatically**, so no Progress Card is needed.
  19. ```
  20. /plugin marketplace add itsAalaa7/adhd-study-coach
  21. /plugin install adhd-study-coach@adhd-study-coach-marketplace
  22. ```
  23. Then say `let's study X`, `quiz me`, `I'm done for today`, or `how am I doing lately`.
  24. **Claude app (claude.ai / Desktop) skill:** download [`adhd-study-coach-skill.zip`](https://github.com/itsAalaa7/adhd-study-coach/raw/main/claude-ai-skill/adhd-study-coach-skill.zip), then Settings → Capabilities → Skills → Upload skill.
  25. ---
  26. ## 🎯 The big idea (read this one)
  27. Two facts, one plan:
  28. | Fact | Source |
  29. |---|---|
  30. | **What works** for learning is already well known: test yourself, and space it out. | Strong general-population science |
  31. | **What's hard for ADHD brains** is *keeping on doing it*: starting, tracking time, waiting for payoff, feeling shame. | ADHD research |
  32. **So this plugin doesn't invent a new "ADHD study method."**
  33. It takes the proven method and **removes the ADHD-specific barriers** to doing it.
  34. ---
  35. ## 🔁 What happens in a session
  36. The agent picks the mode itself. You don't choose.
  37. | # | Mode | When | What it does |
  38. |---|---|---|---|
  39. | 0 | **Onboarding** | First time only | 3 questions, then straight into studying |
  40. | 1 | **Warm-up** | Something is due for review | Quizzes you on old topics *before* new ones |
  41. | 2 | **Teach** | You want something new | Small chunks, one question at a time |
  42. | 3 | **Reflect** | You say "I'm done" | Interviews you, saves a note (+ optional Anki cards) |
  43. | 4 | **Check-in** | Every ~5 sessions | Finds your patterns, tells you what to adopt / drop / do next |
  44. ---
  45. ## 🔬 The science, one feature at a time
  46. Every rule in the agent has a reason. Here's the short version.
  47. **Full citations and honest strength ratings → [`RESEARCH.md`](./RESEARCH.md).**
  48. ### ✅ Strong evidence — the core
  49. | Feature | The science | What you'll notice |
  50. |---|---|---|
  51. | **Quizzes, not re-reading** | *Retrieval practice.* Testing yourself beats re-studying (Roediger & Karpicke 2006; meta-analysis of 217 studies, Adesope et al. 2017). | Warm-ups are questions, never "read your notes again." |
  52. | **Spaced review** | *Spacing effect.* Reviewing at growing gaps beats cramming (Cepeda et al. 2006; 317 experiments). | Topics come back at 1 → 3 → 7 → 16 → 35 → 90 days. |
  53. | **Tiny chunks** | *Cognitive load theory* (Sweller). Working memory is limited. ADHD adults and children show large working-memory differences (Kasper et al. 2012; Alderson et al. 2013). | 4–5 lines per idea. One question per message. |
  54. | **Worked examples that fade** | Full examples help while learning; too much help later backfires (*expertise-reversal effect*). | First time: fully shown. Later: you do more of it. |
  55. | **"It should feel hard"** | *Desirable difficulties* (Bjork & Bjork). Effortful recall sticks better than easy review. | It tells you *why* it's uncomfortable. |
  56. | **Stop the low-value habits** | Highlighting, re-reading and summarizing rate **low utility** (Dunlosky et al. 2013). | One-line redirect to testing yourself. No lecture. |
  57. ### 🟡 Moderate evidence
  58. | Feature | The science | What you'll notice |
  59. |---|---|---|
  60. | **Teach-it-back at the end** | *Self-explanation / generation effect.* Explaining in your own words improves understanding. | Reflect mode is an interview, not a summary written for you. |
  61. | **Mixed topics in warm-up** | *Interleaving* (Rohrer & Taylor 2007). Real effect, smaller and less consistent than testing or spacing. | Due topics are mixed together. |
  62. | **Instant feedback** | *Delay aversion* (Sonuga-Barke). ADHD reward systems respond poorly to "payoff later." | Every answer is graded right away as solid / shaky / blank. Never "wrong." |
  63. | **Visible progress line** | One pediatric ADHD trial found gamified learning helped (2025 RCT, n=80). Applying it to adults is an *inference*. | One line after warm-up: `✅ 3 solid · 🟡 1 shaky`. |
  64. | **Auto-start, no "remember to ask"** | CHADD / NICE guidance: supports that need self-activation get underused. | Warm-up and check-ins run on their own. |
  65. | **Time shown for you** | *Time blindness* (Barkley). Sense of elapsed time is unreliable in ADHD. | Plain time checkpoints: "~10 min in." |
  66. ### 🟠 Weak or anecdotal — included, clearly labeled
  67. | Feature | Honest status |
  68. |---|---|
  69. | **Tiny first step** (against "Wall of Awful") | Clinical framework, not a tested finding. Low risk, so it stays. |
  70. | **Never shame** | Rejection Sensitive Dysphoria has very little direct research. Not shaming a learner is good practice anyway. |
  71. | **Body-doubling offer** | Anecdotal only. Optional, and it never claims to be as good as the strong stuff. |
  72. > **The gap, stated plainly:** there is very little research that tests spaced repetition or AI tutoring *specifically on ADHD learners*. Most of the proven techniques come from general-population studies. The ADHD research explains *why the barriers are real*. That's an honest limit, not a hidden one.
  73. ---
  74. ## 🧩 Rules the agent follows
  75. - ✂️ **Small.** Max 4–5 lines per section. One core idea, bolded.
  76. - 🎯 **One question at a time.** Scenario-based ("you do X and Y happens — why?"), never "define X."
  77. - ⏱️ **Time is external.** It tells you the time so your brain doesn't have to track it.
  78. - 🏁 **65% is "done enough."** If the timebox ends, the rest becomes an open item. You end on a win.
  79. - 🧠 **Memorize vs. look up.** It says which is which, so not everything feels equally heavy.
  80. - 💛 **No shame.** Missed a week? Coming back *is* the skill.
  81. ---
  82. ## 🔒 What it reads and writes (privacy)
  83. Everything is **local**, in the plugin's data folder. Nothing is sent anywhere by this plugin.
  84. If the data-folder variable isn't available, it falls back to `~/.adhd-study-coach/` and tells you once.
  85. ```
  86. <data dir>/
  87. ├── profile.json # subjects, cadence, what it learned about how you learn
  88. ├── review-schedule.json # spaced-repetition schedule, one entry per topic
  89. ├── sessions.log.jsonl # one line per session (used for check-ins)
  90. └── notes/<subject>/
  91. ├── <topic>.md # your reflection note
  92. └── flashcards/<topic>.txt # optional Anki import file
  93. ```
  94. Personal data lives in `profile.json`, **never** in the shared agent file.
  95. ### Safety at a glance
  96. | | |
  97. |---|---|
  98. | Network access | ❌ None. The plugin makes no network calls. |
  99. | Hooks / scripts / MCP servers | ❌ None. It's a single Markdown agent file. |
  100. | Tools the agent may use | Read, Write, Edit, Glob, Grep, Bash, PowerShell — limited to the data folder by its own rules |
  101. | Files it touches | Only the data folder above |
  102. | Stored content treated as | Data, never instructions (guards against injected text in old notes) |
  103. Read the agent yourself — it's one file: [`agents/adhd-study-coach.md`](./agents/adhd-study-coach.md).
  104. ---
  105. ## 💬 What a session looks like
  106. ```
  107. You: quiz me
  108. Coach: 2 things are due: "photosynthesis: light reactions", "cell membranes".
  109. Starting with the first. ~5 min.
  110. A plant sits in green light only. What happens to its rate of
  111. photosynthesis, and why?
  112. You: it slows a lot because chlorophyll reflects green
  113. Coach: Solid. ✅ Chlorophyll absorbs mostly red and blue, so green light
  114. drives little of the reaction. Next one…
  115. …
  116. ✅ 2 solid · 🟡 1 shaky · streak on "cell membranes": 3
  117. Ready for something new, or stop here?
  118. ```
  119. ## 🐛 Support
  120. Bugs and ideas: [GitHub Issues](https://github.com/itsAalaa7/adhd-study-coach/issues).
  121. Security concerns: see [`SECURITY.md`](./SECURITY.md).
  122. ---
  123. ## ❓ Why one agent, not four?
  124. An earlier version had four agents (teacher, reviewer, quizzer, analyst).
  125. It worked, but the review agent only ran **if you remembered to call it** — and that's exactly the thing ADHD makes hard.
  126. One agent that runs its own warm-up removes that failure by design, not by asking you to try harder.
  127. ---
  128. ## ⚠️ Not a clinical tool
  129. This is a **study aid**. It's not a diagnosis, treatment, or medical device, and it doesn't replace clinical care. If you want treatment, talk to a clinician.
  130. ## 📚 About the citations
  131. `RESEARCH.md` was compiled with AI-assisted literature search. The citations are believed accurate but **have not been verified against the original papers**. Please check before citing them academically or clinically, and open an issue or PR if you spot an error.
  132. ## 🤝 Contributing
  133. Welcome:
  134. - Citation corrections
  135. - Places where the agent breaks its own rules
  136. - Places it wrongly assumes a coding context (it should work for any subject)
  137. Open an issue or PR.
  138. ## 📄 License
  139. MIT — see [`LICENSE`](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.