The open-source AI teaching assistant that lives on WhatsApp
You're not teaching alone.

Quick Start · Features · Languages · Content Library · Agent-Native · Docs · Website

Rumi gives every teacher a coach in their pocket. It runs entirely on WhatsApp — the app teachers already have — and offers classroom coaching on real lessons, reading assessments from a voice note, lesson plans, curriculum quizzes, and professional development, in the teacher's own language, 24 hours a day.

It is built to be cloned and run by anyone. Bring your own API keys, point it at a WhatsApp number, and you have a teaching assistant for your schools — no commissioning, no vendor, no lock-in.

# 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 — tools, dependencies, and the `rumi` command
./install.sh

# 3. Connect Rumi to your accounts — guided, one question at a time
rumi setup

# 4. Start it
rumi start

Then message the number Rumi linked and send Hi.

About fifteen minutes, most of it waiting for a Supabase project to start. rumi setup asks in plain language rather than by variable name ("where should Rumi keep its memory", not SUPABASE_URL), checks every value against the real service as you type it, creates the whole database for you, and saves each answer as it goes — so Ctrl+C is safe and running it again picks up where you stopped.

⚠️ By default Rumi links your own WhatsApp account, the same way WhatsApp Web does — so Rumi is your number. You cannot have a useful conversation with yourself, so you need a different number to message it from.

Any of these works: a spare SIM, an old phone, a work phone, a family member's phone, or a second WhatsApp account logged into WhatsApp Web in your browser. Both numbers need WhatsApp installed and active.

If you skip this you will pair successfully, send a message, and see nothing happen — not because anything is broken, but because Rumi is on the other end of your own chat.

The wizard offers to start Redis locally with Docker if you have it, so that row is often one keypress. A Meta WhatsApp Business account is not required to try Rumi — see the two ways to run it.

Optional feature keys (Soniox, ElevenLabs, Uplift, Gamma, Kie.ai, Azure, Mistral) unlock the features that use them, and only those. rumi setup offers them at the end and skipping is a real answer — every one can be added later by setting its key. Each is documented in .env.template.

If install.sh could not put rumi on your PATH, node bin/rumi.js <command> is identical.

Would rather not type it yourself? Open the repo in a coding agent (Claude Code, Cursor, Codex) and say "set me up" — it walks you through the same sequence in conversation, following the /setup skill. Setting up a real deployment (hosting, the Meta webhook, WhatsApp Flows, background workers), or prefer the manual route? SETUP.md has the full walkthrough, including getting a WhatsApp number from scratch.

Rumi's messaging channel is pluggable. You pick one during setup, in plain language, and you can change your mind later.

Moving across is one command: rumi graduate. Teachers, conversations and past assessments all carry over on their own, because Rumi identifies people by phone number rather than by channel. The one thing that cannot follow you is the number itself, so tell your testers to start a chat with the new one.

Future channels (Slack, Telegram, …) plug into the same registry — see docs/onboarding/sandbox-production-design.md.

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.

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 rumi status or rumi doctor anytime to see exactly which features are live and which key would switch each remaining one on.

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 + coaching framework), status (your active sessions), edit-class (roster), and a student-video library.

15 languages, for text chat, voice-note transcription (STT), and spoken replies (TTS) alike. Alongside English, Urdu, Arabic and Spanish, Rumi covers Pakistan's regional languages — Punjabi, Sindhi, Pashto and Balochi (via Meta's MMS-ASR) — Sri Lankan Tamil, and a complete Indian-language suite:

🇮🇳 हिन्दी Hindi · বাংলা Bengali · मराठी Marathi · తెలుగు Telugu · தமிழ் Tamil · ಕನ್ನಡ Kannada

Every one works end to end — teachers chat and send voice notes in their language, get spoken and written replies back, and generate lesson plans localized to their 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 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 --apply

The 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 (and AGENTS.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 asks you for each credential in conversation, checks every one against the real service, creates your database, and hands you the two steps that need human hands (pasting one SQL helper, scanning the WhatsApp QR). It uses the same modules the rumi setup wizard does, so the two paths can't drift. 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.

rumi-platform/
├── bin/rumi.js             # The `rumi` CLI — setup, start, status, doctor, pair, graduate
├── install.sh              # One-time bootstrap: tools, dependencies, .env, the rumi command
├── bot/                    # WhatsApp bot (Node.js + Express)
│   ├── whatsapp-bot.js     # Entry point — webhook, inbound routing, message dispatch
│   ├── shared/
│   │   ├── config/         # Presence-based feature gating, branding, languages, regions
│   │   ├── services/
│   │   │   ├── messaging/  # Pluggable channel drivers (meta | baileys) + text-flow rendering
│   │   │   ├── queue/      # Pluggable queue (sqs | bullmq)
│   │   │   └── …           # LLM, coaching, reading, lesson plans, quiz, video, …
│   │   ├── handlers/       # text / voice / image / flow / exam / attendance
│   │   ├── routes/         # WhatsApp Flow endpoints (also drive the text fallbacks)
│   │   └── utils/          # Structured logging, correlation IDs, html-to-pdf
│   ├── workers/            # Async workers (coaching, video, lesson plans, quiz, exam, …)
│   └── scripts/setup/      # The wizard, doctor, pairing, flow registration, encryption
├── dashboard/              # Observability portal — analytics, health
├── portal/                 # Teacher web portal (React)
├── infrastructure/
│   └── supabase/           # SQL schema (76 tables), RLS policies, seed data + bootstrap
├── docs/                   # Architecture, features, customization, cost, samples
└── .claude/                # Agent-native config — CLAUDE.md routers + 16 operational skills

Teacher on WhatsApp
  → Meta Cloud API (webhook)  ·OR·  linked-device socket (sandbox)
    → one normalized inbound shape → message dispatch
      → user lookup (Supabase) → language detection → feature routing
        → text | voice | image | flow handler
          → LLM (OpenRouter) → reply
          → async job queue (Redis or SQS) → background workers → reports / media
            → delivered back to the teacher on WhatsApp

Both channels converge on the same dispatch, so a feature is written once and works on either. 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.

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-4

Deep (agent-first): this repo is designed to be customized by AI-assisted IDEs. The Agent Customization Guide maps each goal to exact files:

npm test               # the full suite
npm run test:security  # secret scan — no hardcoded credentials
npm run test:schema    # database schema validation
npm run test:setup     # setup tooling
rumi doctor            # live preflight: which services + features are configured
npm run simulate       # CLI simulator — try features 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.

More: docs/monitoring.md · or open the repo in your coding agent and paste the error.

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.