Skip to content
Back to search

Bloom

Hire a private AI tutor for anything — it reads how you actually learn and teaches the next lesson just for you. Bloom's 2-Sigma research as a Claude Code skill + self-hostable web app · 中文优先 苏格拉底式 AI 家教

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Li-Evan/BloomTutor with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Li-Evan/BloomTutor'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/li-evan--bloom/badge.svg)](/listings/li-evan--bloom)

HTML

<a href="/listings/li-evan--bloom"><img src="/api/listings/li-evan--bloom/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.

Requires only [Claude Code](https://claude.com/claude-code). No backend.

git clone https://github.com/Li-Evan/Bloom.git
cd Bloom

# Install the tutor skill locally for this clone
mkdir -p .claude/skills
cp -R skills/bloom-tutor .claude/skills/

claude

Then say: `Create a new folder and help me learn [any topic]`

**Or install it as a plugin** (bundles `bloom-tutor` plus the `learn-*` skills) — in Claude Code:

/plugin marketplace add Li-Evan/Bloom
/plugin install bloom@li-evan

See [GUIDE.md](./GUIDE.md) for the full walkthrough.

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 · 18 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "li-evan",
  3. "owner": {
  4. "name": "Li Zhengping",
  5. "url": "https://github.com/Li-Evan"
  6. },
  7. "metadata": {
  8. "description": "Bloom — a personal AI tutor (Bloom's 2-sigma) as a Claude Code plugin.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "bloom",
  14. "source": "./",
  15. "description": "A personal AI tutor based on Bloom's 2-sigma research: it generates a structured syllabus, teaches one adaptive lesson at a time, and tailors each next lesson to the learner's highlights and feedback. Bundles bloom-tutor plus six learn-* skills."
  16. }
  17. ]
  18. }
README.md · README · 278 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="assets/logo.svg">
  5. <img alt="Bloom" src="assets/logo.svg" width="360">
  6. </picture>
  7. </p>
  8. <p align="center">
  9. <strong>Hire a private AI tutor for anything you want to learn.</strong>
  10. </p>
  11. <p align="center">
  12. <em>Your AI reads how you actually learn — and teaches the next lesson just for you.<br>Built on Bloom's 2-Sigma research: 1-on-1 tutoring = top 2%.</em>
  13. </p>
  14. <p align="center">
  15. <a href="https://github.com/Li-Evan/BloomTutor/stargazers"><img src="https://img.shields.io/github/stars/Li-Evan/BloomTutor?style=social" alt="GitHub stars"></a>
  16. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
  17. <img src="https://img.shields.io/github/last-commit/Li-Evan/BloomTutor" alt="Last commit">
  18. <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+">
  19. <img src="https://img.shields.io/badge/node-20+-blue.svg" alt="Node.js 20+">
  20. <img src="https://img.shields.io/badge/next.js-15-blue.svg" alt="Next.js 15">
  21. <img src="https://img.shields.io/badge/fastapi-0.115+-blue.svg" alt="FastAPI">
  22. </p>
  23. <p align="center">
  24. <a href="https://bloomtutor.app"><strong>🌐 Website</strong></a> · <a href="./README.zh.md">Chinese</a> · English
  25. </p>
  26. <p align="center">
  27. <a href="https://bloomtutor.app"><img src="assets/hero.png" alt="Bloom — from average to the top 2%" width="820"></a>
  28. </p>
  29. ---
  30. In 1984, educational psychologist Benjamin Bloom discovered that students receiving **one-on-one tutoring** scored **2 standard deviations (+2σ)** above the classroom average — jumping to the **top 2%**. Bloom called this the "2 Sigma Problem": the effect is proven, but personal tutors don't scale.
  31. **Bloom solves this with AI.** It generates a structured syllabus, delivers lessons one at a time, reads your annotations and feedback, then tailors the next lesson to your exact understanding level — just like a real tutor would.
  32. ## Two Ways to Use
  33. | Mode | Setup | Best for |
  34. |------|-------|----------|
  35. | **CLI** | Claude Code (or DeepSeek Harness) + terminal | Power users who like Markdown editors |
  36. | **Web** | Browser (Next.js + FastAPI), self-hosted | Visual learners, your own materials and PDFs |
  37. Both follow the same flow: **syllabus → lesson → annotate → feedback → next lesson → evaluation → summary**.
  38. ---
  39. ## Quick Start: CLI Mode
  40. Requires only [Claude Code](https://claude.com/claude-code). No backend.
  41. ```bash
  42. git clone https://github.com/Li-Evan/BloomTutor.git
  43. cd BloomTutor
  44. # Install the tutor skill locally for this clone
  45. mkdir -p .claude/skills
  46. cp -R skills/bloom-tutor .claude/skills/
  47. claude
  48. ```
  49. Then say: `Create a new folder and help me learn [any topic]`
  50. **Or install it as a plugin** (bundles `bloom-tutor` plus the `learn-*` skills) — in Claude Code:
  51. ```text
  52. /plugin marketplace add Li-Evan/BloomTutor
  53. /plugin install bloom@li-evan
  54. ```
  55. **Or use it in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)**: the same skills ship as the `bloomtutor-dsh` plugin on npm:
  56. ```bash
  57. dsh plugin --profile web add bloomtutor-dsh
  58. ```
  59. Or straight from this repository: `dsh plugin --profile web add github:Li-Evan/BloomTutor`.
  60. Details in [integrations/deepseek-harness](./integrations/deepseek-harness/README.md).
  61. See [GUIDE.md](./GUIDE.md) for the full walkthrough.
  62. ## Quick Start: Web Mode
  63. The web app is a self-hosted, single-user tutor: no accounts, no billing. You bring an API key for any OpenAI-compatible model; everything you create stays in your own database.
  64. ### Prerequisites
  65. - Python 3.11+ with [uv](https://docs.astral.sh/uv/)
  66. - Node.js 20+ with [pnpm](https://pnpm.io/)
  67. - An API key for any OpenAI-compatible chat model (OpenAI, DeepSeek, Qwen/DashScope, Moonshot, a local Ollama, …)
  68. ### Setup
  69. ```bash
  70. git clone https://github.com/Li-Evan/BloomTutor.git
  71. cd BloomTutor
  72. make setup # creates .env with a random BACKEND_JWT_SECRET, installs backend and frontend deps
  73. # edit .env: fill in LLM_API_KEY, LLM_BASE_URL and LLM_MODEL
  74. make dev-backend # terminal 1: runs the database migrations, then the API on 127.0.0.1:8000
  75. make dev-frontend # terminal 2: the web app on http://localhost:3000
  76. ```
  77. Open http://localhost:3000, click **New course**, and start learning.
  78. ### Docker
  79. ```bash
  80. make setup # or: cp .env.example .env and fill it in yourself
  81. docker compose up -d --build # then open http://localhost:3000
  82. ```
  83. Data lives in the `bloom-storage` volume (a SQLite database plus the images inside your materials). To use Postgres instead, set `DATABASE_URL` in `.env`.
  84. ### Configuration
  85. | Variable | What it does |
  86. |----------|--------------|
  87. | `LLM_API_KEY`, `LLM_BASE_URL`, `LLM_MODEL` | The model used for syllabi, lessons and answers |
  88. | `LLM_FAST_MODEL` | Optional smaller model for the knowledge map, course placement and selection translation |
  89. | `PDF_READING_MODEL` | Optional vision model for "PDF reading" (page images → Markdown) |
  90. | `LLM_EXTRA_BODY` | JSON passed as `extra_body` on every call, e.g. `{"thinking":{"type":"disabled"}}` for DeepSeek |
  91. | `BACKEND_JWT_SECRET` | Shared by the frontend server and the backend; the backend only accepts tokens signed with it |
  92. | `DATABASE_URL` | Defaults to `backend/storage/bloom.sqlite3` |
  93. | `LANGFUSE_*` | Optional tracing of every model call to [Langfuse](https://langfuse.com) |
  94. ### Security
  95. Bloom has no login: anyone who can open the web app is you. Keep it on `localhost`, or put it behind something that authenticates (a VPN, Tailscale, or a reverse proxy with basic auth) before exposing it. The backend is never published by `docker compose`; it only answers requests signed with `BACKEND_JWT_SECRET`.
  96. ### Upgrading from the previous (Vite) version
  97. The web app was rebuilt on Next.js with a new database schema. The old `bloom.db` is not migrated; the new app starts with an empty database in `backend/storage/`.
  98. ---
  99. ## How It Works
  100. ### Topic or your materials
  101. ```
  102. Describe a goal (optionally upload materials) → Bloom asks a few clarifying questions
  103. ↓
  104. Outline: what you will be able to do, in order → review / edit it
  105. ↓
  106. Read lesson 1 → highlight and ask → write feedback → answer thought questions
  107. ↓
  108. Click "Done reading" → the next lesson reviews your answers, answers your highlights,
  109. follows your feedback and moves on
  110. ↓
  111. Repeat until every mastery item is covered ✅ → evaluation → course summary
  112. ```
  113. ### Project files, web articles, PDF reading
  114. ```
  115. Upload files / a folder / a link / PDFs → each one becomes a page (no outline)
  116. ↓
  117. Read → highlight and ask, or ask about the whole page → mark as read, archive
  118. ↓
  119. What you read feeds the knowledge map and next-step suggestions
  120. ```
  121. ## Features
  122. **Ways to start a course**
  123. - **Topic** — describe what you want to learn; Bloom asks a few clarifying questions about your goal, then designs an outline at the depth you pick (simple / standard / deep)
  124. - **Your materials** — upload PDFs, Word, PowerPoint, Excel, EPUB, Markdown or text (or a ZIP); Bloom reads everything into a knowledge pack and grounds the outline and lessons in it, with source citations
  125. - **Project files** — upload files or a whole folder; each file becomes a page you can read and ask about, no outline needed
  126. - **Web articles** — paste a link to import the article text and images, or use the [browser clipper](./extension/) to save the page you are reading
  127. - **PDF reading** (experimental) — a vision model turns each PDF page into reflowable Markdown with formulas, tables and figures, next to the original PDF
  128. **Learning**
  129. - **Outline first** — review the outline before lesson 1; edit it or tell Bloom how to change it
  130. - **Adaptive lessons** — each lesson reviews your answers to the last one's questions, answers what you highlighted, and follows your feedback (shorter, more examples, slower…); the last lesson is an evaluation, then a course summary
  131. - **Highlight Q&A** — select any passage (also inside PDFs) to ask; keep asking follow-ups in the same thread; mark passages without asking
  132. - **Ask this lesson** — a chat about the whole lesson or file, no selection needed
  133. - **Selection translation** — translate a passage into the interface language, with what it means in context and the word roots of a term
  134. - **Teaching style** — presets (concise, analogy, rigorous…) or your own instructions, for every course
  135. - **Reading comfort** — table of contents, reading time, text size, fonts, light / dark theme, Chinese / English interface
  136. **Seeing the whole**
  137. - **Knowledge map** — every course is placed on a shared tree of knowledge (a frozen snapshot of Wikipedia's Vital Articles), with the topics you actually read and neighbouring directions to explore
  138. - **Next steps** — three course-ready suggestions grown from your history; save them to a wishlist or start one
  139. - **User center** — activity heatmap and streaks, all your highlight notes in one place, export to Markdown
  140. - **Material folders** — move, rename, edit, archive or delete files in material courses
  141. ## Skills
  142. Bloom ships a set of portable **[Claude Code](https://claude.com/claude-code) skills** in [`skills/`](./skills/) — self-contained capability packs you can copy into `~/.claude/skills/` (global) or any project's `.claude/skills/` and use anywhere.
  143. | Skill | What it does |
  144. |-------|-------------|
  145. | **bloom-tutor** | The full interactive tutoring system as one skill — syllabus → adaptive lessons → `???` annotations → evaluation → summary. CLI mode, packaged and portable. |
  146. | **learn-deep** | Default deep-dive entry — runs all five lenses below in one pass, then helps you pick a direction |
  147. | **learn-crossover** | Learn a new concept by leveraging what you already know (structural analogies) |
  148. | **learn-occam** | Decide whether / how deeply something is worth learning (ROI, just-enough) |
  149. | **learn-graph** | Build a knowledge-graph map of a field plus a learning path |
  150. | **learn-prototype** | Learn by building the crappiest working prototype, then iterating |
  151. | **learn-feynman** | Verify true understanding by explaining it back |
  152. Each folder is dependency-free: copy it into a skills directory, then just talk to Claude Code (e.g. *"help me learn X"*, *"I'm done reading"*). The same folders also run in DeepSeek Harness through the `bloomtutor-dsh` plugin.
  153. ## Tech Stack
  154. | Layer | Technology |
  155. |-------|-----------|
  156. | Backend | Python, FastAPI, SQLAlchemy 2, Alembic; SQLite by default, Postgres supported |
  157. | Frontend | Next.js 15 (App Router), React 19, Tailwind CSS 4, Radix UI, next-intl, pdf.js |
  158. | AI | Any OpenAI-compatible chat completions API |
  159. | Container | Docker, docker compose |
  160. | Font | Outfit, Public Sans, JetBrains Mono |
  161. ## Commands
  162. ```bash
  163. make setup # create .env, install dependencies
  164. make dev-backend # migrations + API with hot reload (127.0.0.1:8000)
  165. make dev-frontend # web app dev server (localhost:3000)
  166. make test # backend pytest + frontend tests
  167. make up / make down # docker compose start / stop
  168. ```
  169. ## Project Structure
  170. ```
  171. ├── GUIDE.md # CLI usage guide
  172. ├── package.json # makes the repo the bloomtutor-dsh DeepSeek Harness plugin (no app code)
  173. ├── .env.example # configuration template
  174. ├── backend/
  175. │ ├── app/ # FastAPI app: courses.py (course engine), knowledge*.py / coordinate.py (knowledge map),
  176. │ │ # lesson_chat.py, translate.py, recommendations.py, uploads / web_import / document_import ...
  177. │ ├── alembic/ # database migrations (the second one imports the knowledge tree)
  178. │ ├── data/knowledge/ # the knowledge tree release (Wikipedia Vital Articles level 5 snapshot)
  179. │ └── tests/
  180. ├── frontend/
  181. │ └── src/
  182. │ ├── app/[locale]/ # pages: /learn (courses, lessons, map, next), /me (user center)
  183. │ ├── components/ # learn/, me/, site/ (header, footer), ui/
  184. │ └── lib/ # API clients, lesson logic
  185. ├── extension/ # browser web clipper
  186. ├── docs/ARCHITECTURE.md # how the pieces fit together
  187. ├── example/ # pre-built topics for CLI mode
  188. ├── integrations/deepseek-harness/ # the bloomtutor-dsh plugin for DeepSeek Harness
  189. ├── site/ # marketing website (standalone Astro static build, decoupled from the app)
  190. └── skills/ # portable Claude Code skills (bloom-tutor + learn-*)
  191. ```
  192. ## The Science
  193. | Concept | What it means |
  194. |---------|--------------|
  195. | **Bloom's 2 Sigma** | 1-on-1 tutoring = +2σ performance over classroom |
  196. | **Mastery Learning** | Don't move on until the concept is truly understood |
  197. | **Socratic Method** | Ask questions, don't hand answers |
  198. | **Spaced Retrieval** | Thought question reviews at lesson start reinforce memory |
  199. | **Adaptive Path** | Content adjusts to individual feedback in real-time |
  200. ## Star History
  201. <a href="https://star-history.com/#Li-Evan/BloomTutor&Date">
  202. <picture>
  203. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Li-Evan/BloomTutor&type=Date&theme=dark" />
  204. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Li-Evan/BloomTutor&type=Date" />
  205. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Li-Evan/BloomTutor&type=Date" width="640" />
  206. </picture>
  207. </a>
  208. ## License
  209. [MIT](LICENSE). Third-party components, fonts and the knowledge-tree data keep their own licences: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Ratings and comments

Sign in to rate this skill.

Sign in

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