Skip to content
Back to search

Superlearn

Learn anything, deeply from inside Claude Code, Codex or KiloCode

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/raiyanyahya--superlearn/badge.svg)](/listings/raiyanyahya--superlearn)

HTML

<a href="/listings/raiyanyahya--superlearn"><img src="/api/listings/raiyanyahya--superlearn/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Requirements:** [Claude Code](https://claude.com/claude-code), [OpenAI Codex](https://developers.openai.com/codex/), or [Kilo](https://kilo.ai) — plus Python 3.9+. That's it — every script is Python standard library, so there is nothing to `pip install`.

**Install from the marketplace (Claude Code):**

/plugin marketplace add raiyanyahya/superlearn
/plugin install superlearn@superlearn-marketplace

**Or run it from a clone (Claude Code):**

git clone https://github.com/raiyanyahya/superlearn
cd your-project
claude --plugin-dir /path/to/superlearn

**OpenAI Codex or Kilo:** clone the repo and run the installer once —

git clone https://github.com/raiyanyahya/superlearn
python3 superlearn/scripts/install.py --codex      # and/or --kilocode

It copies the same playbook, packaged as a standard Agent Skill, into each tool's global config (stamping the clone's path, so re-run it if you move the clone). Then invoke it from any project: `$superlearn <topic>` in Codex, `/superlearn <topic>` in Kilo — or just ask to learn something and the skill triggers itself. Two setup notes:

- **Codex** sandboxes network access by default, and Superlearn needs it (the YouTube/arXiv scrapers, and your browser reaching the local app). Add to `~/.codex/config.toml`:

  [sandbox_workspace_write]
  network_access = true

- **Kilo** has web search built in for its own provider; on other providers enable it under **Settings → Web Tools** (or `"web_search": true` in `kilo.jsonc`).

Running the agent *inside* the clone needs no install at all — both tools auto-discover the skill from `.agents/skills/` (and Kilo picks up the `/superlearn` command from `.kilo/commands/`).

**Then just ask:**

/superlearn how Postgres internals work
/superlearn transformer neural networks
/superlearn rust ownership — I already know C++
/superlearn react hooks for my frontend interview
/superlearn diffusion models, research mode

A few minutes later:

✦ Superlearn is live → http://localhost:4321

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 · 14 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": "superlearn-marketplace",
  3. "owner": {
  4. "name": "Raiyan Yahya",
  5. "url": "https://github.com/raiyanyahya"
  6. },
  7. "plugins": [
  8. {
  9. "name": "superlearn",
  10. "source": "./",
  11. "description": "Learn anything, beautifully. AI research pipeline + interactive local learning boards, powered by your Claude Code subscription."
  12. }
  13. ]
  14. }
README.md · README · 367 lines

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

  1. <div align="center">
  2. # ✦ Superlearn
  3. <p>
  4. <a href="https://claude.com/claude-code"><img src="https://img.shields.io/badge/Claude%20Code-plugin-D97757?logo=claude&logoColor=white" alt="Works with Claude Code"></a>
  5. <a href="https://developers.openai.com/codex/"><img src="https://img.shields.io/badge/OpenAI%20Codex-agent%20skill-000000" alt="Works with OpenAI Codex"></a>
  6. <a href="https://kilo.ai"><img src="https://img.shields.io/badge/Kilo%20Code-agent%20skill-6E56CF" alt="Works with Kilo Code"></a>
  7. </p>
  8. **Learn anything, deeply — from inside your coding agent.**
  9. Give it a topic. It researches the live web, designs a page that fits the subject,
  10. and serves you an interactive learning board that keeps growing as you ask for more.
  11. *No API keys. Runs on the agent subscription you already have — Claude Code,
  12. OpenAI Codex, or Kilo. Everything saved on your disk.*
  13. </div>
  14. <div align="center">
  15. <em>One real board, top to bottom — <code>/superlearn how Postgres internals work</code>.<br/>
  16. 38 blocks: concepts, diagrams, charts, runnable code, papers and talks. Nothing trimmed.</em>
  17. </div>
  18. ![A full Superlearn board on Postgres internals, scrolled end to end](docs/screenshots/hero-board.png)
  19. ---
  20. ## What it is
  21. Superlearn is a Claude Code plugin that also ships as a standard [Agent Skill](https://agentskills.io) for **OpenAI Codex** and **Kilo** (formerly Kilo Code). You type `/superlearn <topic>`; the agent researches the live web itself, pulls real videos from YouTube and papers from arXiv, runs an iterative research loop until the topic is genuinely covered, synthesizes everything into a curated learning board, and launches a local web app to study it in.
  22. It is built for people who want **mastery**, not a summary. There are no quizzes, no streaks, no gamification — the material is research notes, concept deep-dives, diagrams and mindmaps, curated papers, working code, and learning roadmaps. Blocks are as long as the teaching requires and nothing is trimmed.
  23. And it doesn't stop when the page loads: keep talking to the same agent session — *"go deeper on X"*, *"add the original papers"*, *"make it feel more academic"* — and the page updates itself in place within seconds.
  24. ## Quick start
  25. **Requirements:** [Claude Code](https://claude.com/claude-code), [OpenAI Codex](https://developers.openai.com/codex/), or [Kilo](https://kilo.ai) — plus Python 3.9+. That's it — every script is Python standard library, so there is nothing to `pip install`.
  26. **Install from the marketplace (Claude Code):**
  27. ```
  28. /plugin marketplace add raiyanyahya/superlearn
  29. /plugin install superlearn@superlearn-marketplace
  30. ```
  31. **Or run it from a clone (Claude Code):**
  32. ```bash
  33. git clone https://github.com/raiyanyahya/superlearn
  34. cd your-project
  35. claude --plugin-dir /path/to/superlearn
  36. ```
  37. **OpenAI Codex or Kilo:** clone the repo and run the installer once —
  38. ```bash
  39. git clone https://github.com/raiyanyahya/superlearn
  40. python3 superlearn/scripts/install.py --codex # and/or --kilocode
  41. ```
  42. It copies the same playbook, packaged as a standard Agent Skill, into each
  43. tool's global config (stamping the clone's path, so re-run it if you move the
  44. clone). Then invoke it from any project: `$superlearn <topic>` in Codex,
  45. `/superlearn <topic>` in Kilo — or just ask to learn something and the skill
  46. triggers itself. Two setup notes:
  47. - **Codex** sandboxes network access by default, and Superlearn needs it (the
  48. YouTube/arXiv scrapers, and your browser reaching the local app). Add to
  49. `~/.codex/config.toml`:
  50. ```toml
  51. [sandbox_workspace_write]
  52. network_access = true
  53. ```
  54. - **Kilo** has web search built in for its own provider; on other providers
  55. enable it under **Settings → Web Tools** (or `"web_search": true` in
  56. `kilo.jsonc`).
  57. Running the agent *inside* the clone needs no install at all — both tools
  58. auto-discover the skill from `.agents/skills/` (and Kilo picks up the
  59. `/superlearn` command from `.kilo/commands/`).
  60. **Then just ask:**
  61. ```
  62. /superlearn how Postgres internals work
  63. /superlearn transformer neural networks
  64. /superlearn rust ownership — I already know C++
  65. /superlearn react hooks for my frontend interview
  66. /superlearn diffusion models, research mode
  67. ```
  68. A few minutes later:
  69. ```
  70. ✦ Superlearn is live → http://localhost:4321
  71. ```
  72. ## How it works
  73. ```
  74. /superlearn <topic>
  75. │
  76. ▼
  77. ┌─────────────────┐ Your own files in .superlearn/sources/ (PDFs, docs) are
  78. │ 1. SWEEP │ read first, then Claude searches and reads the live web
  79. └─────────────────┘ itself; scrapers fetch real YouTube IDs + arXiv papers.
  80. ▼
  81. ┌─────────────────┐ Claude writes a curriculum plan: a subtopic checklist
  82. │ 2. PLAN │ sized to the topic, foundations → advanced.
  83. └─────────────────┘
  84. ▼
  85. ┌─────────────────┐ For every subtopic: search, read, save the evidence to
  86. │ 3. RESEARCH ⟳ │ the trail, write dense notes, tick the box. Repeat
  87. └─────────────────┘ until saturated. Parallel agents on big topics.
  88. ▼
  89. ┌─────────────────┐ Claude DESIGNS the page for this subject (layout +
  90. │ 4. DESIGN & │ theme), authors the board — summary, roadmap, concepts,
  91. │ AUTHOR │ diagrams, code, glossary, real videos and papers —
  92. └─────────────────┘ then runs it through the schema validator.
  93. ▼
  94. ┌─────────────────┐ A local server hosts the app. You learn — and keep
  95. │ 5. SERVE │ prompting. The page hot-reloads with new material,
  96. │ & ITERATE ⟳ │ badging whatever changed.
  97. └─────────────────┘
  98. ```
  99. ## The app
  100. ### Six layouts, switchable live
  101. | View | What you get |
  102. |---|---|
  103. | **Board** | Masonry of learning cards — scan and dive |
  104. | **Notes** | A single-column document, ordered for reading |
  105. | **Grid** | Uniform card grid |
  106. | **Mindmap** | An auto-generated map of the whole territory, plus every diagram |
  107. | **Canvas** | The whole board as a **whiteboard** — see below |
  108. | **Feed** | Everything, full-width, in sequence |
  109. ![Mindmap view](docs/screenshots/view-mindmap.png)
  110. ### The whiteboard
  111. Canvas view lays the entire board out spatially, like a wall you'd build in Miro: **one dashed frame per section**, numbered in reading order, with connectors tracing the path between them. Drag to pan, scroll to zoom, `Fit` to fill the width, `All` for the bird's-eye. Section labels counter-scale against the zoom, so the map stays legible from any distance.
  112. Claude authors the sections (`"section": "MVCC"` on each block), so the frames are real chapters — not type buckets. Boards without sections still get a canvas, grouped by what the blocks are.
  113. And it's **your** wall: grab any frame by its label and drag it where you want it. The arrangement saves into the board JSON, survives reloads and Claude's edits — when Claude adds a new section, it auto-places without disturbing what you arranged. `Reset` re-flows everything.
  114. ![Canvas view — the whole Postgres board as a whiteboard](docs/screenshots/canvas-fit.png)
  115. <div align="center"><em>…and zoomed in, cards are fully live — code runs, diagrams zoom, notes save:</em></div>
  116. ![Canvas view zoomed into the MVCC section](docs/screenshots/canvas-zoom.png)
  117. ### Focus mode, and knowing where you are
  118. **Focus** walks the board one card at a time — arrow keys to move, Esc to leave — and marks each card read as you go. Every card also has a ✓ tick, and the board carries a **reading progress bar** that persists across sessions. Open a half-studied board and it tells you exactly where you left off; Focus resumes at your first unread card.
  119. ![Focus mode — one card, full attention](docs/screenshots/focus-mode.png)
  120. ![The progress bar under the board title](docs/screenshots/progress.png)
  121. ### Claude designs the page for the topic
  122. Six complete visual identities — `midnight`, `blueprint`, `terminal`, `paper`, `sepia`, `arctic` — plus an optional custom accent, chosen per subject. Engineering topics arrive on a blueprint grid; systems programming in a terminal; philosophy as a sepia document. Never the same default twice out of habit.
  123. <table>
  124. <tr>
  125. <td width="50%"><img src="docs/screenshots/theme-blueprint.png" alt="Blueprint theme"><br><em><code>blueprint</code> — engineering & systems</em></td>
  126. <td width="50%"><img src="docs/screenshots/theme-terminal.png" alt="Terminal theme"><br><em><code>terminal</code> — programming & infra</em></td>
  127. </tr>
  128. </table>
  129. ### Built to show, not just tell
  130. Boards render **Mermaid diagrams and mindmaps**, **real typeset math** via KaTeX (`$$\frac{QK^\top}{\sqrt{d_k}}$$`, not "Q K transpose over root d k"), **figures**, and **charts drawn from actual data** — line, bar, and scatter, with hover tooltips, a legend, and a "Show data" table for every one.
  131. <table>
  132. <tr>
  133. <td width="50%"><img src="docs/screenshots/math.png" alt="A concept card with typeset math"><br><em>Real TeX, inline and display</em></td>
  134. <td width="50%"><img src="docs/screenshots/chart.png" alt="A chart card with two series"><br><em>Charts from real numbers, with a table view</em></td>
  135. </tr>
  136. </table>
  137. The chart palette isn't chosen by eye. It's six hues validated with a colorblindness checker against all six theme surfaces — lightness band, chroma floor, adjacent-pair CVD separation, contrast — with a separate set of steps for light themes rather than an automatic flip. Series count is capped where the colors stop being reliably distinguishable, and the app says so instead of quietly cycling hues.
  138. Every diagram and figure is **click-to-zoom**: full-screen, wheel to scale, drag to pan, Escape to leave. Detail is worth putting in.
  139. ![A diagram opened full-screen](docs/screenshots/diagram-zoom.png)
  140. ### Code you can read — and run
  141. Code blocks and markdown fences are **syntax-highlighted** in colors that belong to the board's theme, not a bolted-on stylesheet. Every token was checked to clear 4.5:1 contrast against the tightest code background of the six. Untagged fences stay plain on purpose — auto-detection is confidently wrong on pseudo-code, and miscolored is worse than uncolored.
  142. **JavaScript, Python, and HTML blocks get a Run button** and execute right on the card: JS and HTML instantly, Python on a real CPython via Pyodide (NumPy, pandas, matplotlib, SymPy and friends included). Output streams into a console pane below the code, with timing, and a Stop button that kills an infinite loop without freezing the page.
  143. ![Running Python inside a board](docs/screenshots/run-python.png)
  144. The code is **untrusted** — it was authored from scraped pages — so it runs in an iframe with `sandbox="allow-scripts"` and deliberately *without* `allow-same-origin`. The frame gets an opaque origin: it cannot read the app's DOM, its storage, or the boards API, and it cannot rewrite its own sandbox. Results cross back by `postMessage`, matched on frame identity. Blocks that can't work in a browser (a PyTorch example, say) are marked `"runnable": false` and simply don't offer the button.
  145. ### Your notes — and your highlights — live in the board
  146. Annotate any card in your own words. Notes save **into the board JSON**, survive exports and shares, and Claude reads them on the next iteration — write *"still don't get this"* and ask for a rewrite, and it knows exactly what you meant.
  147. ![An annotated card with a cross-board link](docs/screenshots/annotation.png)
  148. **Select any passage and highlight it.** Highlights save into the board too, and Claude treats them as signal: a highlighted sentence is what resonated, several highlights on one card mean *go deeper here*. Rendering uses the CSS Custom Highlight API, so marking up a card never touches its DOM.
  149. ![A highlighted passage inside a card](docs/screenshots/highlight.png)
  150. ### The library is a map, not a list
  151. The **Library** button draws every board as a node — emoji, block count, your reading progress — with the cross-board `related` links as edges. Boards that share ideas are visibly connected; click any node to jump. The more you learn, the more the graph fills in.
  152. ![The library graph](docs/screenshots/library.png)
  153. ### A table of contents that knows what you've read
  154. On wide screens, Notes and Feed views get a **contents rail**: every block, grouped by section, with your read-ticks mirrored as dots. Click to jump; the entry you're reading stays lit.
  155. ![The contents rail alongside the notes view](docs/screenshots/toc-rail.png)
  156. ### Real spaced repetition
  157. Flashcards are scheduled with SM-2 (Again / Hard / Good / Easy, growing intervals per card). The **Review** button runs everything due **across all your boards** in one session, with a live due count. One click exports any deck as TSV for Anki.
  158. ![Cross-board review session](docs/screenshots/review-session.png)
  159. ### The full research trail, kept
  160. Every plan, note, and raw evidence capture is saved and browsable in the app — so you can always audit where a claim came from.
  161. ![Research trail browser](docs/screenshots/research-trail.png)
  162. ### Plus
  163. - **"Updated" badges** on cards Claude changed since your last visit
  164. - **Cross-board links** — related concepts jump between boards and highlight the target card
  165. - **Wallpaper picker** — the ❖ button swaps the board's background (theme design, plain, grid, dots, hatch, accent-tinted aurora) **and its base**: the theme's surface, pure white, or pure black. White and black move the whole ink scale, so everything stays readable. Per board, remembered
  166. - **Click-to-play video lectures**, and copy buttons on every code block
  167. - **Full-text filtering**, JSON export, print/PDF
  168. - **Standalone HTML export** — one file that opens anywhere; `--offline` bakes in the diagram and math engines and the board's figures too, so it works on a plane
  169. ## Modes
  170. `study` is the default. Ask for another in plain words (*"for my interview"*, *"survey the literature"*, *"as a reference"*) or with `--mode`. The mode changes **what gets researched** and **how the page presents it** — not just the wording.
  171. | Mode | What changes |
  172. |---|---|
  173. | `study` | Balanced conceptual mastery — the default experience |
  174. | `interview` | Likely questions with strong answers, what interviewers listen for, red flags, live-coding katas, fast-scan layout |
  175. | `research` | Literature map: seminal + recent papers with why-each-matters, state of the field, open problems, reading order |
  176. | `documentation` | A working reference: code-first usage patterns, configuration tables, gotchas, exact terminology |
  177. ## Everything is saved on your disk
  178. ```
  179. .superlearn/
  180. ├── sources/ ← drop your own PDFs, papers, and docs here; they're read first
  181. ├── research/ the full trail per topic — plan, synthesized notes, raw evidence
  182. ├── boards/ portable board JSON — share with anyone who has the plugin
  183. └── exports/ standalone single-file HTML — opens anywhere, offline, no server
  184. ```
  185. Nothing leaves your machine except the research requests themselves. Boards are plain JSON you can read, diff, and version-control.
  186. ## Keep iterating
  187. The session stays live. While the server runs, keep talking to your agent:
  188. - *"Add a section on error correction"*
  189. - *"Go deeper on decoherence — include the original papers"*
  190. - *"Make it feel more academic"* (theme and layout change, live)
  191. - *"Build me a second board on quantum hardware"* — boards accumulate and cross-link
  192. The page picks up each change within seconds and marks what's new.
  193. ## Scripts
  194. Every script is standalone, stdlib-only, and usable on its own.
  195. | Script | What it does |
  196. |---|---|
  197. | `scrape_youtube.py` | Real video IDs, titles, channels, durations |
  198. | `scrape_arxiv.py` | Papers via the official arXiv API — abstracts, authors, PDF links |
  199. | `validate_board.py` | Schema, theme/mode values, video-ID format, URL validity, chart data shape, language tags, sections, highlights, canvas layout, Mermaid hygiene |
  200. | `export_html.py` | Bakes a board into one self-contained HTML file (`--offline` inlines Mermaid, KaTeX, highlight.js and figures) |
  201. | `serve.py` | Local app server + boards/research API |
  202. | `publish.py` | Pushes your exported boards to a `gh-pages` branch with a generated index |
  203. | `install.py` | Installs the skill/command/agents into OpenAI Codex and Kilo global config |
  204. Serve existing boards any time without re-researching:
  205. ```bash
  206. python3 scripts/serve.py --boards-dir .superlearn/boards --port 4321
  207. ```
  208. The board in the screenshot above ships in [`examples/`](examples/) — serve it and click around before installing anything:
  209. ```bash
  210. python3 scripts/serve.py --boards-dir examples --port 4321
  211. ```
  212. ## Board format
  213. Boards are plain JSON: `title`, `emoji`, `topic`, `mode`, `theme` (preset + optional accent), `layout`, `sources`, and an array of typed blocks — each optionally tagged with a `section` that becomes its frame on the whiteboard. Blocks carry your `annotation` and `highlights`; the board carries your dragged `canvas` arrangement — `summary`, `roadmap`, `concept`, `note`, `diagram` (Mermaid), `chart`, `image`, `code`, `video`, `resource`, `flashcards`, `glossary`. Markdown fields render TeX.
  214. The full schema and the rules Claude follows live in [`skills/superlearn/SKILL.md`](skills/superlearn/SKILL.md). Validate any board with `python3 scripts/validate_board.py <board.json>`.
  215. ## Repository layout
  216. ```
  217. .claude-plugin/ plugin + marketplace manifests (Claude Code)
  218. commands/ the /superlearn slash command (Claude Code)
  219. skills/superlearn/ the research → design → author → serve → iterate playbook
  220. agents/ parallel subtopic researcher (Claude Code)
  221. .agents/skills/ the same playbook as a portable Agent Skill (Codex + Kilo)
  222. .codex/agents/ the researcher as a Codex sub-agent role
  223. .kilo/ the /superlearn command + researcher subagent for Kilo
  224. AGENTS.md repo instructions for agents that read the AGENTS.md standard
  225. scripts/ scrapers, validator, exporter, server, publisher, installer
  226. app/ the Superlearn web app (single file, zero build step)
  227. examples/ ready-to-serve example boards
  228. tests/ stdlib-only test suite (python3 -m unittest discover -s tests)
  229. ```
  230. ## Notes on privacy and security
  231. - **No API keys.** Superlearn runs on the Claude Code, Codex, or Kilo subscription you already have; nothing is proxied through a third party.
  232. - **The server is loopback-only** by default and validates the `Host` header, so a web page can't reach it via DNS rebinding. Bind wider deliberately with `--host` if you want to read boards from your phone.
  233. - **Board content is treated as untrusted** — it's authored from scraped pages. The app escapes all rendered markdown, refuses non-`http(s)` links, and pins video embeds to validated IDs; exports neutralize the payload for HTML script context.
  234. - **Research files are served read-only**, with path-traversal protection.
  235. ## The researched data isn't ours
  236. Superlearn researches the live web, and it's worth being plain about whose
  237. work that is: **not ours, and not yours.** The articles it reads, the videos
  238. it finds, the papers it lists — all of it belongs to the people who made it.
  239. The tool is built to respect that:
  240. - **Web research goes through Claude's own sanctioned search and fetch
  241. tools** — there is no bundled search-engine scraper. Claude searches, reads,
  242. and cites like a (very fast) research assistant.
  243. - **It gathers references, not copies.** Boards contain Claude's own synthesis
  244. with the sources cited and linked; article extracts live only in your
  245. private research trail on your own disk, like a read-later app.
  246. - **Videos play through YouTube's own embedded player** — the sanctioned path
  247. that serves the creator's views. Nothing is downloaded or ripped.
  248. - **Papers come from the official arXiv API**, which exists for this.
  249. - **Volume is tiny and polite** — a handful of requests per topic, no
  250. crawling, no login walls, no CAPTCHAs, no paywall circumvention, ever.
  251. - **Follow the links.** The resources on every board are the invitation to go
  252. read the originals — that's the point of citing them.
  253. If you extend the scrapers, keep them this way: identify honestly, stay slow,
  254. respect a site's refusal, and never republish content you didn't write.
  255. ## License
  256. [MIT](LICENSE). Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md);
  257. security reports via [SECURITY.md](SECURITY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

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