🤖 MyClassBot: Your Personal Coding Tutor on Telegram

Learn programming by chatting with an AI tutor that remembers your conversation
Runs 100% on your machine using local AI (Ollama) - no data leaves your computer.

---

🎯 What This Does

MyClassBot turns Telegram into an interactive coding classroom:

• You send programming questions → Bot replies with explanations/examples
• Remembers your conversation history (unlike basic chatbots)
• Works completely offline - your chats stay private
• Built for teaching: explains concepts step-by-step, gives code examples, helps debug

Example conversation:

You: How do I make a list in Python?
Bot: Use square brackets! Try: my_list = [1, 2, 3]

You: How do I add an item?
Bot: Use .append(): my_list.append(4)  # Now it's [1, 2, 3, 4]

---

✅ What You Need (5-Minute Checklist)

Before starting, verify you have:

Tool	Version	Install Command	Verify
Node.js	20+ (LTS)	brew install node (macOS) or nodejs.org	node --version → v20.x.x
Ollama	Latest	ollama.com/download	ollama --version
ngrok	Latest	brew install ngrok (macOS) or ngrok.com/download	ngrok version
Telegram	Any	telegram.org/dl	Already have it!
Trigger.dev Account	Free	Sign up at trigger.dev	Verify email

💡 Mac users with Homebrew: Install all three at once:
brew install node ollama ngrok

---

🚀 5-Minute Quick Start (Copy-Paste Ready)

Follow these steps exactly to get your bot running in under 5 minutes:

1️⃣ Setup Project

git clone <your-repository-url>
cd MyClassBot
npm install

2️⃣ Configure Environment

cp .env.example .env
# Edit .env with your values (see next section)

3️⃣ Start Services (4 Terminals)

Terminal 1 (ngrok - makes your computer accessible):

ngrok http 3000
# → COPY THE HTTPS URL (looks like https://abc123.ngrok-free.app)

Terminal 2 (Ollama - your local AI):

ollama serve

Terminal 3 (Trigger.dev - processes requests):

npx trigger.dev@latest dev

Terminal 4 (Webhook - receives Telegram messages):

npm run dev:webhook

4️⃣ Connect Everything

1. Update .env with your ngrok URL from Terminal 1:

   TELEGRAM_WEBHOOK_URL=https://abc123.ngrok-free.app/telegram/webhook

2. Register webhook (run once):

   npm run register:webhook

3. Test in Telegram: Message your bot! 🎉

---

📦 Detailed Setup Guide

Step 1: Get Your Bot Token from Telegram

1. Open Telegram → search for @BotFather
2. Send /newbot
3. Follow prompts to name your bot
4. Copy the token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
5. Paste into .env:
   TELEGRAM_TOKEN=your-token-here

Step 2: Get Your Trigger.dev Key

1. Go to Trigger.dev Dashboard
2. Create a new project (or use existing)
3. Click "API Keys" → "Create Development Key"
4. Copy the key (starts with tr_dev_)
5. Paste into .env:
   TRIGGER_SECRET_KEY=your-key-here

Step 3: Install & Test Ollama

# Download Ollama from ollama.com if not installed
ollama serve &  # Start in background
ollama pull qwen2.5:7b  # Download the AI model (~4.7GB)
ollama list  # Should show qwen2.5:7b

Step 4: Setup ngrok Tunnel

ngrok http 3000

Important: Keep this running! You'll see:

Forwarding                    https://abc123.ngrok-free.app -> http://localhost:3000

Copy that HTTPS URL (the https://abc123.ngrok-free.app part)

Step 5: Configure Environment File

Edit .env with your values:

# FROM TELEGRAM BOTFATHER
TELEGRAM_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

# GENERATE THIS (run: openssl rand -hex 32)
TELEGRAM_WEBHOOK_SECRET=a5098f0b847e374f636ed9312d24655f27f57ab18f0f09286ba7ae2c3fee47f9

# FROM NGROK STEP 4 (UPDATE THIS!)
TELEGRAM_WEBHOOK_URL=https://abc123.ngrok-free.app/telegram/webhook

# FROM TRIGGER.dev DASHBOARD
TRIGGER_SECRET_KEY=tr_dev_0NwSOjW08CX5GpM8cOQO

# KEEP THESE AS IS UNLESS YOU KNOW WHAT YOU'RE DOING
OLLAMA_URL=http://127.0.0.1:11434/api/generate
OLLAMA_MODEL=qwen2.5:7b
CONVERSATION_LOG_PATH=conversations/telegram-conversations.jsonl
CONVERSATION_TRANSCRIPT_PATH=conversations/telegram-conversations.txt
PORT=3000

Step 6: Register Webhook with Telegram

npm run register:webhook

You should see: Telegram webhook registered successfully.

Step 7: Start All Services (Keep These Running!)

You need 4 terminals open simultaneously:

Terminal	Command	What It Does
1	ngrok http 3000	Creates public URL for Telegram
2	ollama serve	Runs your local AI model
3	npx trigger.dev@latest dev	Processes requests (your bot's "brain")
4	npm run dev:webhook	Listens for Telegram messages

⚠️ Keep all 4 terminals open while using the bot. Closing any will break the pipeline.

Step 8: Test Your Bot!

1. Open Telegram
2. Search for your bot's username
3. Tap Start
4. Send a message:
   "Hello! Can you explain what a variable is in Python?"
5. Wait 5-15 seconds for response (first response may be slower as model loads)

---

🔧 Complete Startup Pipeline (Production-Ready)

Here's the exact command sequence for daily use:

# TERMINAL 1: Public tunnel (run first, get URL)
ngrok http 3000

# TERMINAL 2: Local AI server
ollama serve

# TERMINAL 3: Bot's reasoning engine
npx trigger.dev@latest dev

# TERMINAL 4: Message receiver
npm run dev:webhook

# ONE-TIME SETUP (after ngrok URL is known):
# 1. Update .env with your ngrok URL
# 2. Run: npm run register:webhook

📝 Your .env Template (Fill in the blanks)

# 1. FROM @BotFather in Telegram
TELEGRAM_TOKEN=your_telegram_bot_token_here

# 2. GENERATE THIS: openssl rand -hex 32
TELEGRAM_WEBHOOK_SECRET=your_generated_secret_here

# 3. FROM NGROK (UPDATE EVERY TIME YOU RESTART NGROK)
TELEGRAM_WEBHOOK_URL=https://your-ngrok-subdomain.ngrok-free.app/telegram/webhook

# 4. FROM TRIGGER.dev DASHBOARD
TRIGGER_SECRET_KEY=your_tr_dev_key_here

# 5. KEEP DEFAULTS (change only if you know why)
OLLAMA_URL=http://127.0.0.1:11434/api/generate
OLLAMA_MODEL=qwen2.5:7b
CONVERSATION_LOG_PATH=conversations/telegram-conversations.jsonl
CONVERSATION_TRANSCRIPT_PATH=conversations/telegram-conversations.txt
PORT=3000

---

🎓 How the AI Remembers Your Conversation

Unlike basic chatbots, MyClassBot actually remembers what you talked about:

1. Every exchange gets saved to conversations/telegram-conversations.jsonl
2. Before responding, it fetches your last 5 messages with this bot
3. It includes that history in the AI's prompt as context
4. Result: The AI sees the full conversation flow!

Example:

You: How do I make a loop in JavaScript?
Bot: Use for loops! For example: for(let i=0; i<5; i++){ console.log(i); }

You: How do I stop it early?
Bot: Use break! Like: for(let i=0; i<10; i++){ if(i===5) break; console.log(i); }

---

📞 Need Help? Try These First

1. Check all 4 terminals are running without errors
2. Look at the Trigger.dev dashboard: cloud.trigger.dev → Your project → "Runs" tab
3. Test Ollama directly:

   curl -X POST http://localhost:11434/api/generate \
     -H "Content-Type: application/json" \
     -d '{"model":"qwen2.5:7b","prompt":"Say hello in Python","stream":false}'

4. Verify webhook is reachable:
   Visit https://your-ngrok-url.ngrok-free.app/telegram/webhook in browser - should show {"status":"ok"}

Still stuck?

• Telegram issues: BotFather Help
• Trigger.dev issues: Docs | Discord
• Ollama issues: GitHub Issues
• ngrok issues: Docs | Status

---

🎉 You're Ready to Teach!

Your bot is now:

• ✅ Running completely on your computer
• ✅ Remembering your conversation history
• ✅ Ready to help you (or anyone you share it with) learn to code
• ✅ 100% private - no data leaves your machine

Go teach something amazing! 🚀

💡 Pro tip: Share your bot with friends! Just give them your Telegram username and they can start learning immediately (they'll need to start a chat with your bot first).

---

Built with ❤️ for lifelong learners. Questions? Open an issue or reach out!
Last updated: July 18, 2026