Bloom AI Tutor
A self-hosted or Claude Code AI tutor that turns Bloom's 2-Sigma research into Socratic, adaptive one-on-one lessons on any topic.
- Source repo
- Li-Evan/BloomTutor
- Stars
- ★ 323
- Last updated
- 4d ago
- License
- MIT
- Primary language
- Python
- FA score
- 57/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformClaude Code · OpenAI API
- You'll need
- Typical use
- A self-learner starting a new field wants structure: describe the topic, review the outline, then work through adaptive lessons ending in an evaluation.
- Main limitation
- The web app has no authentication — anyone who can open it is you, so it must sit behind localhost, a VPN, Tailscale or a basic-auth reverse proxy.
- Website
- bloomtutor.app ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-17+2.6 ★/day over 7 days
- Source review
- 57/100 · Major gaps
What does this agent do, and when should you use it?
Bloom is an open-source study tool built around Benjamin Bloom's 2-Sigma Problem: one-on-one tutoring lifts students two standard deviations above the classroom average, but human tutors don't scale. It ships two entry points — a portable bloom-tutor skill for Claude Code or DeepSeek Harness that needs only a terminal, and a self-hosted web app made of a FastAPI backend and a Next.js 15 frontend with SQLite by default and optional Postgres. Both follow one loop: generate a syllabus, deliver lessons one at a time, collect highlight questions and written feedback, then shape the next lesson around your answers, ending in an evaluation and a course summary. Courses can be driven by a topic or grounded in your own PDFs, Office files, EPUB, Markdown, ZIP archives, project folders and imported web articles, with an optional vision model that reflows PDF pages into Markdown. Bloom brings no model of its own: you supply an API key for any OpenAI-compatible endpoint, and everything you create stays in your own database.
You describe a learning goal or upload materials; Bloom asks a few clarifying questions and produces an outline of what you will be able to do, which you can review, edit, or set to simple/standard/deep depth. Lessons then run sequentially: each opens by reviewing your answers to the previous lesson's thought questions, answers what you highlighted (inside PDFs too, or marked passages without asking), and follows feedback such as shorter, more examples, or slower. The final lesson is an evaluation followed by a course summary; a separate “Ask this lesson” chat covers a whole lesson or file, and selection translation renders a passage in the interface language with contextual meaning and word roots. On the materials path, modules under backend/app (uploads, web_import, document_import) turn files, folders, links and the browser clipper into readable pages; knowledge*.py and coordinate.py place each course on a shared knowledge tree built from a snapshot of Wikipedia's Vital Articles (level 5) and propose three next courses. A user center shows an activity heatmap and streaks, collects highlight notes, and exports them to Markdown.
- A self-learner starting a new field wants structure: describe the topic, review the outline, then work through adaptive lessons ending in an evaluation.
- An engineer onboarding to an unfamiliar framework from a pile of internal docs or PDFs: upload the material pack and get lessons with source citations.
- A Claude Code user who lives in the terminal: copy skills/bloom-tutor into .claude/skills/ and drive it conversationally with “help me learn X” and “I'm done reading”.
- Someone reading papers or long web articles: save the page with the browser clipper or paste a link, then read, highlight and ask about it.
- A learner tracking progress over months: check the activity heatmap and exported notes, and pick a next direction from the knowledge map.
- An individual or small team that wants a private instance: bring up the web app with docker compose on a single machine with no accounts.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
docker compose up -d --build # then open http://localhost:3000
- Ports
8000·3000- Environment variables
BACKEND_JWT_SECRETLLM_API_KEYLLM_BASE_URLLLM_MODELLLM_FAST_MODELPDF_READING_MODEL- Config files
.env.env.example- Runtime
- Python 3.11+ · Node.js 20+
- Install notes cover
- Docker
How do you install or deploy this agent?
CLI mode needs only Claude Code and no backend:
git clone https://github.com/Li-Evan/BloomTutor.git
cd BloomTutor
# Install the tutor skill locally for this clone
mkdir -p .claude/skills
cp -R skills/bloom-tutor .claude/skills/
claudeOr install it as a plugin, which bundles bloom-tutor plus the learn-* skills:
/plugin marketplace add Li-Evan/BloomTutor
/plugin install bloom@li-evanDeepSeek Harness users can install the same skills through the plugin:
dsh plugin --profile web add github:Li-Evan/BloomTutorWeb mode requires Python 3.11+ with uv, Node.js 20+ with pnpm, and an API key for any OpenAI-compatible chat model:
git clone https://github.com/Li-Evan/BloomTutor.git
cd BloomTutor
make setup # creates .env with a random BACKEND_JWT_SECRET, installs backend and frontend deps
# edit .env: fill in LLM_API_KEY, LLM_BASE_URL and LLM_MODEL
make dev-backend # terminal 1: runs the database migrations, then the API on 127.0.0.1:8000
make dev-frontend # terminal 2: the web app on http://localhost:3000Or via Docker:
make setup # or: cp .env.example .env and fill it in yourself
docker compose up -d --build # then open http://localhost:3000How do you use this agent?
In CLI mode, start Claude Code and talk to it in plain language:
Create a new folder and help me learn [any topic]In web mode, open http://localhost:3000, click New course, and choose either Topic or Your materials. The configuration that matters lives in .env:
# LLM_API_KEY, LLM_BASE_URL, LLM_MODEL: the model used for syllabi, lessons and answers
# LLM_FAST_MODEL: optional smaller model for the knowledge map, course placement and selection translation
# PDF_READING_MODEL: optional vision model for "PDF reading" (page images → Markdown)
# LLM_EXTRA_BODY: JSON passed as extra_body on every call, e.g. {"thinking":{"type":"disabled"}} for DeepSeek
# BACKEND_JWT_SECRET: shared by the frontend server and the backend
# DATABASE_URL: defaults to backend/storage/bloom.sqlite3Day-to-day commands:
make setup # create .env, install dependencies
make test # backend pytest + frontend tests
make up / make down # docker compose start / stopWhat are this agent's strengths and limitations?
- The pedagogy is concrete, not decorative: mastery learning, Socratic questioning and spaced retrieval are wired into a course engine that reviews last lesson's answers and adjusts the next one.
- No vendor lock-in on models — any OpenAI-compatible chat completions endpoint works, including DeepSeek, Qwen/DashScope, Moonshot and a local Ollama.
- One skills set serves three entry points (Claude Code, the bloomtutor-dsh plugin, the web app), and each folder under skills/ is dependency-free and copyable.
- Genuinely grounded material path: PDF, Word, PowerPoint, Excel, EPUB, Markdown, text, ZIP, folders and web links, with source citations kept in the lessons.
- Self-hosted and single-user by design: no accounts or billing, data in your own SQLite (or Postgres) and Docker volume, optional Langfuse tracing of model calls.
- The web app has no authentication — anyone who can open it is you, so it must sit behind localhost, a VPN, Tailscale or a basic-auth reverse proxy.
- Upgrading from the previous Vite release does not migrate bloom.db; the new app begins with an empty database in backend/storage/.
- You must bring model API keys and pay per-token usage, and experimental PDF reading needs a separate vision model.
- Web mode means maintaining two toolchains (Python and Node), an .env file and a JWT secret alongside the model configuration.
- There is no multi-user, role or billing layer, so classroom- or institution-scale deployment is out of scope.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Bloom AI Tutor This agent | 57 · Major gaps | — | ★ 323 | 4d ago | Python | Claude Code · OpenAI API |
| YouTube Fetcher to Markdown | 81 · Good | Agent plugin / skillFree | ★ 544 | 1mo ago | Python | Codex · Claude Code |
| Obsidian Second Brain | 63 · Some gaps | Agent plugin / skillFree + model costs | ★ 5.4k | 3d ago | Python | Codex · Claude Code |
| Folio | 77 · Good | Self-hosted serviceFree + model costs | ★ 90 | 2d ago | TypeScript | ChatGPT · Codex · Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
Least privilege: backend binds 127.0.0.1, compose does not publish the backend, CORS restricted to WEB_URL — reasonable defaults (2); but no login means anyone reaching the app is 'you', and the JWT secret is only length-checked, so deducted. User confirmation: SKILL.md enforces one-document-at-a-time and blocks user-triggered summary (product design, not destructive), but uploads/imports/deletes show no explicit confirmation flow, 1. Data-flow transparency: README states data stays in your own DB, optional Langfuse tracing, bring-your-own gateway; main.py deliberately avoids logging URL/keys — good (2). Sensitive data: conftest forces offline tests away from real gateways/Langfuse and secret length is validated, but no encryption or retention policy for uploaded PDFs/notes, 2. Dependency security: secret-scan and frozen lockfile installs exist, but no vulnerability scanning/SBOM, 1. External effects: web import, browser clipper and PDF vision model make outbound calls with no stated rate limits or domain allowlist, 1. Rollback: only notes the old Vite DB is not migrated and the new DB starts empty; no backup/rollback guidance, 1. Source attribution: LICENSE, THIRD_PARTY_NOTICES, font OFL notes and knowledge-tree provenance (Wikipedia Vital Articles) are stated, 2.
Self-consistency: SKILL.md decision tree, references index and README flow agree; main.py fails fast on missing config, 2. Dependency availability: README pins Python 3.11+/Node 20+/uv/pnpm; CI installs frozen from uv.lock and pnpm-lock, 2. Failure messages: startup errors for missing JWT/LLM_MODEL are explicit, global handler returns a friendly detail with CORS headers, housekeeping logs and retries, 2.
Audience and scenarios: separates CLI and Web modes for learners and self-hosters, 2. Capability boundaries: SKILL.md caps one document per turn, ≤2 Socratic rounds, and forbids user-triggered summary — clear boundaries, 2. Trigger precision: descriptions list Chinese/English trigger phrases and scenarios; learn-deep defines a default entry with single-lens exceptions, 2. Environment fit: supports OpenAI-compatible gateways, Ollama, SQLite/Postgres and Docker, 2.
Information architecture: README is well structured with a project tree and docs/ARCHITECTURE pointer, 2. Install notes: complete multi-path steps for CLI, plugin, DSH, Web and Docker, 3. Naming stability: plugin name bloom, package bloomtutor-dsh and skill bloom-tutor coexist with mismatched versions 1.0.0/0.1.0/0.3.0, 2. Examples and FAQ: example/ and GUIDE.md exist, but no FAQ in the sample, 2. Known limitations: README flags experimental PDF reading, no-login exposure and no DB migration, 2. License: full MIT text plus third-party notices, 3. Versioning/changelog: only version fields, no CHANGELOG, 1. Maintenance responsibility: author named (Li Zhengping/Evan) but publisher is unverified and no maintenance commitment or security contact, 1.
Output usability: produces syllabus/lesson/summary Markdown with templates defined in references, directly usable, 2. Marginal value: packages Bloom 2-sigma with Socratic/Feynman methods into portable skills — real increment, though similar learning skills are common, 2. Cost-benefit: each lesson needs multiple model calls and Web mode needs self-hosted DB and frontend; cost is non-trivial and quality depends on the model, 1.
Claim traceability: README cites Bloom 1984 and Wikipedia Vital Articles but gives no concrete links or data sources, 1. Cross-source corroboration: README, SKILL.md and plugin.json agree on features, but the +2σ effect claim has no in-repo evidence, 1. Fact/inference separation: README blends research findings with product claims (e.g. 'pushes learning to +2σ') without marking proven vs inferred, 1.
- Web mode has no login: anyone who can reach the app is treated as you; put it behind VPN or authenticated reverse proxy before exposing it.
- Uploaded materials, web import and the browser clipper send content to the configured model gateway; verify data-egress and privacy compliance yourself.
- The old Vite database is not migrated; back up before upgrading — no rollback or backup procedure is provided.
- Publisher identity is unverified and no maintenance commitment or security contact is stated; assess long-term availability yourself.
- The +2σ effectiveness claim lacks in-repo verifiable evidence; treat it as product vision, not a proven result.
FAQ
Can I use it without paying for any model?
Is it safe to expose the web app on the public internet?
Can I point it at a local or non-OpenAI model?
Where does my learning data live?
What is the knowledge map built from?
Is Bloom AI Tutor open source?
Is Bloom AI Tutor still maintained?
Who makes Bloom AI Tutor?
What is Bloom AI Tutor's official website?
Thanks — we use this to improve the page.