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.

Stars
★ 323
Last updated
4d ago
License
MIT
Primary language
Python

At a glance

Works with
Universal · cross-platformClaude Code · OpenAI API
You'll need
Claude Code (CLI mode)Python 3.11+uvNode.js 20+pnpmDocker (optional)OpenAI-compatible API keyShell / CLINetwork accessLocal filesystem
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

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.

  1. A self-learner starting a new field wants structure: describe the topic, review the outline, then work through adaptive lessons ending in an evaluation.
  2. 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.
  3. 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”.
  4. 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.
  5. A learner tracking progress over months: check the activity heatmap and exported notes, and pick a next direction from the knowledge map.
  6. 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_SECRET LLM_API_KEY LLM_BASE_URL LLM_MODEL LLM_FAST_MODEL PDF_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/

claude

Or install it as a plugin, which bundles bloom-tutor plus the learn-* skills:

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

DeepSeek Harness users can install the same skills through the plugin:

dsh plugin --profile web add github:Li-Evan/BloomTutor

Web 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:3000

Or via Docker:

make setup                   # or: cp .env.example .env and fill it in yourself
docker compose up -d --build # then open http://localhost:3000

How 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.sqlite3

Day-to-day commands:

make setup            # create .env, install dependencies
make test             # backend pytest + frontend tests
make up / make down   # docker compose start / stop

What are this agent's strengths and limitations?

Pros
  • 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.
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Major gaps
57/ 100 5-point scale 2.9 / 5
Trust 14/29
Reliability 9/14
Adaptability 12/18
Convention 12/18
Effectiveness 7/13
Verifiability 3/8
Why each dimension lost points
Trust14 / 29 · 2.4/5

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.

Reliability9 / 14 · 3.2/5

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.

Adaptability12 / 18 · 3.3/5

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.

Convention12 / 18 · 3.3/5

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.

Effectiveness7 / 13 · 2.7/5

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.

Verifiability3 / 8 · 1.9/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 16, 2026 Reviewed revision d3d9c0b60958 New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/bloomtutor.svg)](https://followagents.com/en/agents/bloomtutor)
<a href="https://followagents.com/en/agents/bloomtutor"><img src="https://followagents.com/badge/bloomtutor.svg" alt="FARS review"></a>

FAQ

Can I use it without paying for any model?
CLI mode rides on your existing Claude Code or DeepSeek Harness session, so there is no separate backend to configure. Web mode requires LLM_API_KEY, LLM_BASE_URL and LLM_MODEL — without them no syllabus or lesson can be generated.
Is it safe to expose the web app on the public internet?
Not directly. It is a single-user app with no login; the backend is never published by docker compose and only answers requests signed with BACKEND_JWT_SECRET. Put it on localhost, or behind a VPN, Tailscale, or a reverse proxy with basic auth.
Can I point it at a local or non-OpenAI model?
Yes. Any OpenAI-compatible chat completions API works; the README names OpenAI, DeepSeek, Qwen/DashScope, Moonshot and a local Ollama, and LLM_EXTRA_BODY injects extra parameters per call (for example disabling thinking on DeepSeek).
Where does my learning data live?
By default in SQLite at backend/storage/bloom.sqlite3; under Docker it sits in the bloom-storage volume together with images extracted from your materials. Set DATABASE_URL to use Postgres instead, and export highlight notes to Markdown from the user center.
What is the knowledge map built from?
Each course is placed on a shared tree of knowledge taken from a level-5 snapshot of Wikipedia's Vital Articles, shipped in backend/data/knowledge/ and loaded by an Alembic migration. Third-party components, fonts and that data keep their own licences, listed in THIRD_PARTY_NOTICES.md.
Is Bloom AI Tutor open source?
Yes. The source code is on GitHub (Li-Evan/BloomTutor) under the MIT licence.
Is Bloom AI Tutor still maintained?
Yes. The latest commit on GitHub is from 2026-11-17, within the last 30 days.
Who makes Bloom AI Tutor?
Bloom AI Tutor is published on GitHub by the account Li-Evan. FollowAgents has not verified which person or company is behind that account.
What is Bloom AI Tutor's official website?
The project's GitHub repository lists https://bloomtutor.app/ as its website. That link is set by the repository owner; the source code itself is on GitHub (Li-Evan/BloomTutor).
Was this page helpful?
View on GitHub ↗ Install ↓

Host ecosystems

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts