The open-source AI Teaching Assistant that runs on WhatsApp
You're not teaching alone.
Features · Quick Start · Agent-Native · Customize · Docs · Website
Rumi is an open-source AI teaching companion that runs on WhatsApp — giving teachers 24/7 access to classroom coaching, reading assessments, lesson plans, quizzes, and professional development, in their own language, on the device they already carry.
It's built to be cloned and run by anyone, anywhere: set your own API keys, point it at your own WhatsApp number, and you have a teaching assistant for your schools — no commissioning, no vendor lock-in. And because the whole repo is agent-native, you can set it up and adapt it by talking to an AI coding agent — see how ↓.
Across the world, millions of teachers work in isolation — in rural schools, multigrade classrooms, and under-resourced systems where instructional coaches simply don't exist. Traditional professional development reaches teachers once or twice a year at best. The gap between what teachers need and what the system provides is enormous.
Rumi fills that gap. By meeting teachers on WhatsApp — the world's most widely used messaging app — Rumi provides instant coaching on real lessons, reading-fluency assessment, curriculum-aligned content, and multilingual support, all on the phone already in their pocket. The core insight: the best time to coach a teacher is right after they teach, and the best tool is the one they already have.
Why open source? Good teaching support shouldn't depend on which country or company you happen to work for. Any ministry, NGO, school network, or research team can stand up their own instance — adapt the frameworks to their curriculum, run it in their languages, keep their data in their own systems, and improve it for everyone.
Every feature lives on WhatsApp. Click any feature for its own page — what it is, how it works, and the API key(s) that switch it on.
| Feature | What it does | Switches on when you set |
|---|---|---|
| 💬 AI Chat | Ask any teaching question by text or voice; get an expert, pedagogy-grounded answer | core (uses OPENROUTER_API_KEY); voice needs SONIOX_API_KEY |
| 📝 Registration | Friendly WhatsApp onboarding for teachers | always on (core) |
| 🎯 Classroom Coaching | A class recording → framework-scored report + reflective conversation | SONIOX_API_KEY |
| 📖 Reading Assessment | A student reads aloud → fluency, accuracy, pronunciation, comprehension | SONIOX_API_KEY |
| 📋 Lesson Plans | A topic + grade → a full lesson-plan PDF | GAMMA_API_KEY |
| 📸 Pic-to-LP | A photo of a textbook page → an illustrated 2-page lesson plan | KIE_API_KEY |
| 📚 Homework | Pick a class + chapters → a curriculum homework bundle PDF | HOMEWORK_FLOW_ID |
| 🧠 Quiz | Teacher sends a topic quiz to a class; students answer on their parents' WhatsApp, teacher gets a results report | core (uses OPENROUTER_API_KEY) |
| 🎬🎓 Video Quizzes | A curriculum video → its quiz, 3 s later — pictures, voice notes, class share links, and a next-morning reteach report. Ships with the open Taleemabad content library (see below ↓) | one import script + DEFAULT_REGION=pakistan |
| 🗣️ Voice Messages | Full spoken interaction in many languages | SONIOX_API_KEY + ELEVENLABS_API_KEY |
| 🎬 Video Generation | A topic → a short narrated educational video | VIDEO_GENERATION_ENABLED + KIE_API_KEY |
| ✅ Attendance | Voice- or tap-based attendance via WhatsApp Flows | always on (core) |
| 🧮 Exam Checker | Photograph answer sheets → vision OCR + AI grading | MISTRAL_API_KEY |
No tiers, no toggles to hunt for. Rumi gates features by presence: set a feature's API key and it switches on; leave it blank and it stays off cleanly — the bot never crashes over a missing key. Run
npm run doctoranytime to see which features are live for your configuration.
Go deeper: browse the full feature library · understand how lesson plans get routed in LP_PATHS.md · or look at a real sample coaching report (PDF) rendered by the actual pipeline.
Utility flows round it out — settings (language + framework), status (your active sessions), edit-class (roster), and a student-video library — each presence-gated on its WhatsApp Flow id.
Rumi meets teachers in their own language — for text chat, voice-note transcription (STT), and spoken replies (TTS) alike. Alongside English, Urdu, Arabic, Spanish, and Pakistan's regional languages, Rumi now ships a complete Indian-language suite:
🇮🇳 हिन्दी Hindi · বাংলা Bengali · मराठी Marathi · తెలుగు Telugu · தமிழ் Tamil · ಕನ್ನಡ Kannada
Every one works end to end — teachers can chat and send voice notes in their language, get spoken and written replies back, and generate lesson plans localized to Indian classrooms (₹ money problems, locally familiar names and contexts). Pick a language anytime with /language, or just message Rumi in your own script. Which languages appear is driven per-region by config (region_features), so a deployment shows only what it serves.
▶ 68 seconds: a phone on a charpai, one message, and 890 lessons — watch the film
Rumi now ships with a real, complete content library — free and openly hosted. Between 2015 and 2021, Taleemabad's content team hand-wrote question banks, hand-drew the artwork, and studio-recorded voice clips for the Taleemabad Student App, used by hundreds of thousands of Pakistani children. That entire archive has been rescued, matched to its 890 curriculum videos (Nursery–Grade 6, English + Urdu), QA-certified question by question, and rebuilt for WhatsApp:
- A teacher sends
/video, browses grade → subject → topic, and the video lands in her chat. Three seconds later she's offered its quiz — 15 questions with per-answer feedback, picture options she can actually tap, and phonics questions asked by voice note. - She can forward one link to her class WhatsApp group; every child plays in their own 1:1 chat, and she gets a next-morning PDF naming exactly what to reteach and why the class got it wrong.
- All media is served from a public CDN — the videos, all 3,217 illustrations, and all 15,557 voice clips — so your clone needs zero content hosting. One command imports the whole library:
node bot/scripts/setup/import-video-quiz-library.js --applyThe library is Pakistani national-curriculum content, so the quiz feature is region-gated to pakistan out of the box (DEFAULT_REGION=pakistan in .env switches it on — the seed data does the rest). If you serve another curriculum, the gate is one row of config, and the full pipeline for building your own corpus is documented in docs/features/video-quizzes.md.
Rumi is agent-native: the repository is structured so a coding agent (Claude Code, Cursor, Codex, …) can read it, set it up, debug it, and customize it with you. This is what makes "clone and run it yourself" realistic for a small, non-specialist team.
- Progressive-disclosure context. A root
CLAUDE.md(andAGENTS.md) orients the agent, then routes it down to folder guides (bot/CLAUDE.md,infrastructure/CLAUDE.md) and, on demand, to 16 operational skills under.claude/skills/— coaching, reading-assessment, registration, lesson-plan routing, whatsapp-flows, debugging, logging, database analysis, QA, the pre-merge checklist, and more. The agent loads only what the task needs. - Just ask. Open the repo in your agent and say "set me up" — it reads the guides, walks the
/setupflow, runsnpm run doctorandnpm run bootstrap:db, and registers your WhatsApp Flows. Or say "swap the coaching framework to TEACH" and it follows the customization guide to the exact files. - Guard-railed for safety. CI runs a secret scan (gitleaks) plus conformance guards that keep the schema, the docs, and the agent skills honest — so an agent's changes can't silently break a clone or leak a credential.
Start at CLAUDE.md → it points the way.
# 1. Fork this repo on GitHub, then clone YOUR fork
git clone https://github.com/YOUR-ORG/rumi-platform.git
cd rumi-platform
# 2. Install dependencies
npm install && cd bot && npm install && cd ..
# 3. Configure environment — copy the template and fill the REQUIRED values
# (8 required services: 7 ship as placeholders you must set; REDIS_URL defaults to a local instance.
# `npm run doctor` lists exactly what's still missing.)
cp .env.template .env
# SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, OPENROUTER_API_KEY, REDIS_URL,
# WHATSAPP_TOKEN, PHONE_NUMBER_ID, WABA_ID, WEBHOOK_VERIFY_TOKEN
# (each optional feature's keys are documented inline, grouped by feature)
# 4. Check your configuration — pings every service you configured and prints
# a green/red matrix of which features are live
npm run doctor
# 5. Set up the database (applies schema + RLS + seed to a fresh Supabase project)
npm run bootstrap:db
# 6. Deploy (Railway, Docker, or any Node host), point your WhatsApp webhook at
# your deployment, then send "Hi" to your bot number.The whole flow is designed to be driven by an AI setup agent — see Built to be run by an AI agent above, and SETUP.md for the complete manual walkthrough (including getting a WhatsApp number from scratch).
| Requirement | Where to get it | For |
|---|---|---|
| GitHub account | github.com | Fork the repo |
| Node.js 18+ | nodejs.org | Run the bot |
| Supabase project | supabase.com (free tier works) | Database |
| Redis | Railway / Upstash | Sessions + job queue |
| OpenRouter key | openrouter.ai/keys | All AI text |
| WhatsApp Business | Meta Business Manager | The channel |
Optional feature keys (Soniox, ElevenLabs/Uplift, Gamma, Kie.ai, Azure, Mistral) are only needed for the features that use them — each is documented in .env.template.
rumi-platform/
├── bot/ # WhatsApp bot (Node.js + Express)
│ ├── whatsapp-bot.js # Entry point — webhook, message routing
│ ├── shared/
│ │ ├── config/ # Presence-based feature gating, branding, languages, regions
│ │ ├── services/ # LLM, coaching, reading, lesson plans, quiz, video, …
│ │ ├── handlers/ # text / voice / image / flow / exam / attendance
│ │ └── utils/ # Structured logging, correlation IDs, html-to-pdf
│ ├── workers/ # Async workers (coaching, video, lesson plans, quiz, exam, …)
│ └── scripts/setup/ # doctor, flow registration, encryption, state
├── dashboard/ # Observability portal — analytics, health
├── portal/ # Teacher web portal (React)
├── infrastructure/
│ └── supabase/ # SQL schema, RLS policies, seed data + bootstrap script
├── docs/ # Architecture, features, customization, cost, samples
└── .claude/ # Agent-native config — CLAUDE.md routers + 16 operational skills
Teacher on WhatsApp
→ Meta Cloud API → POST /webhook → Express handler
→ user lookup (Supabase) → language detection → feature routing
→ text | voice | image | flow handler
→ LLM (OpenRouter) → response
→ async job queue (Redis or SQS) → background workers → reports / media
→ delivered back to the teacher on WhatsApp
A correlation id threads each request across the webhook, the queue, and the workers, so any flow can be traced end to end. See docs/architecture.md for the full picture, and LP_PATHS.md for the lesson-plan routing in particular.
Rumi is meant to be adapted to your context — your curriculum, your frameworks, your languages, your brand.
Quick (environment variables):
BOT_NAME=MyAssistant
ORG_NAME=My School Network
SUPPORT_CONTACT=help@example.org
LLM_MODEL=anthropic/claude-sonnet-4Deep (agent-first): this repo is designed to be customized by AI-assisted IDEs. The Agent Customization Guide maps each goal to exact files:
| I want to… | Guide |
|---|---|
| Swap the coaching framework (TEACH / Danielson / custom) | Section 1 |
| Use ASER / EGRA instead of DIBELS for reading | Section 2 |
| Change the lesson-plan format (5E, UbD, …) | Section 3 |
| Add a language | Section 4 |
| Switch LLM provider/model | Section 5 |
| Rebrand the bot | Section 11 |
| Layer | Technology | Purpose |
|---|---|---|
| Runtime | Node.js 18+ | Server-side JavaScript |
| Web | Express.js | Webhook + API routes |
| Messaging | WhatsApp Business Cloud API | Messages, media, interactive Flows |
| AI / LLM | OpenRouter (500+ models) | Chat, analysis, content |
| Database | Supabase (PostgreSQL) | Tables with Row-Level Security |
| Queue | Redis or AWS SQS (pluggable via QUEUE_DRIVER) |
Transcription, reports, video, exams |
| Speech-to-Text | Soniox, Whisper, Modal MMS-ASR | Multilingual transcription |
| Text-to-Speech | ElevenLabs (+ Uplift for Urdu/regional) | Voice replies, reflective questions |
| PDFKit / pdfmake / Playwright | Coaching & reading reports | |
| Images / Video | Kie.ai (Nano Banana Pro), FFmpeg | Educational visuals & video |
| OCR | Mistral vision (+ Chandra, Surya) | Exam-sheet scanning |
| Pronunciation | Azure Speech (optional) | Reading-assessment scoring |
| Hosting | Railway / Docker / any Node host | Deployment |
| Observability | Console + correlation IDs; Axiom optional | Structured logs + tracing |
npm test # full suite (run via node tests/run.js)
npm run test:security # secret scan — no hardcoded credentials
npm run test:schema # database schema validation
npm run test:setup # setup tooling
npm run doctor # live preflight: which services + features are configured
npm run simulate # CLI simulator (test without WhatsApp)Every push and PR is gated by CI: an automated secret scan (gitleaks) plus conformance guards that verify the schema, the docs, the agent skills, and the link web all stay honest.
| Doc | What it covers |
|---|---|
| SETUP.md | Full setup, incl. getting a WhatsApp number from scratch |
| docs/features/ | Per-feature deep dives (what / how / enable) — one page each |
| docs/LP_PATHS.md | How a lesson-plan request is routed (pre-generated vs Gamma vs photo) |
| docs/architecture.md | System architecture & message flow |
| CLAUDE.md + .claude/ | Agent-native context: the progressive-disclosure routers + the 16 operational skills |
| docs/agent-customization.md | Agent-first deep customization (frameworks, languages, branding) |
| docs/cost-guide.md | Monthly cost estimates — core baseline + per-feature add-ons |
| docs/monitoring.md | Observability & debugging |
| docs/railway-operations.md | Running on Railway (scaling, logs, workers) |
| docs/pulling-updates.md | Keeping your fork in sync with upstream |
| docs/samples/ | Sample artifacts (e.g. a rendered coaching report) |
| SECURITY.md | Security policy & responsible disclosure |
| .github/CONTRIBUTING.md | Development setup, code style, testing, PR guidelines |
Contributions are welcome. See .github/CONTRIBUTING.md for development setup, code style, testing, and PR guidelines.
Rumi is built by Taleemabad and shared with the world as open source. The name comes from Jalaluddin Rumi, the 13th-century poet and teacher who believed that education is not the filling of a vessel but the kindling of a flame.
Website: hellorumi.ai · Research: hellorumi.ai/research
Apache License 2.0 — see LICENSE. You are free to use, modify, and distribute this software. We encourage contributing improvements back to the community.