Maya 🤖

Your personal WhatsApp assistant that never misses a deadline.

Development status: Core and Phases 2–5 are implemented. Media reading, Google Calendar, and daily VU Classic To Do checks require opt-in setup. Live checks for Calendar and VU login remain with the owner.

If you're in a busy WhatsApp group (a class, a course, a team, a community), you know the problem: the important stuff gets buried. A quiz date is posted at 11 PM, someone changes the room the next morning, and by Friday it's lost under 200 messages of "ok" and "thanks". You find out the deadline was yesterday.

Maya fixes that. She sits quietly in your WhatsApp, reads the groups you choose, picks out the things that matter, and reminds you before it's too late. You can also just ask her:

You: Anything due this week? Maya: Your MTH501 quiz is Tuesday at 9 AM, and CS101 assignment 3 is due Thursday at 11:59 PM. You've got this 🌿

---

What Maya can do

• 👂 Listens only to the groups you pick. She never posts in them.
• 🧠 Understands messages with AI: quizzes, assignments, exams, room changes, cancelled classes. If a date changes, she updates it. Optional image and PDF reading covers supported media in the same chosen groups.
• ⏰ Reminds you about tasks due today and tomorrow, plus a weekly plan when Maya is running.
• 💬 Answers questions when you message her. In separate mode, every direct owner message gets a reply; self mode uses her name as a trigger.
• 👀 Views only your WhatsApp Status in separate mode and sends you a short private comment when she can read its text, caption, photo, or supported video. She does not store Status content or turn it into tasks, and ignores other people's Status updates. Photo and video comments send the media to Gemini and use the configured MEDIA_MAX_BYTES limit, independently of MEDIA_ENABLED (which controls group media). Unsupported or oversized media without a caption is viewed without a comment.
• 📚 Tracks VU Classic To Do deadlines for quizzes and assignments through an optional daily portal check or a manual CSV import.
• 🔒 Runs on your own machine. Messages and tasks are stored locally in SQLite; selected group text is sent to Gemini for analysis.
• 💸 API costs depend on your Gemini plan and usage. Check your model's pricing and set a budget alert before leaving Maya running.

How it works, in plain words

1. Maya connects to WhatsApp as a linked device, the same way WhatsApp Web does.
2. New text messages and media captions in your chosen groups are saved locally. When media reading is enabled, supported images and PDFs are sent to Gemini, and their extracted text is saved instead of the file.
3. Every few minutes, she sends the new messages to an AI (Google Gemini), which pulls out tasks and dates.
4. She sends reminders and answers only to you, in your own chat.

Want the technical details? See ARCHITECTURE.md.

---

Before you start: please read this

Maya uses an unofficial WhatsApp library. WhatsApp doesn't offer an official way to read groups from a personal account, so Maya uses Baileys, an open-source library that works like WhatsApp Web. This is against WhatsApp's Terms of Service, and accounts can get banned. Maya is built to be careful: she's read-only in groups, sends very few messages, and only to you. But the risk is never zero.

👉 The safest setup is a second phone number (a cheap SIM) just for Maya. You can start with your own number and switch later. It takes two minutes.

Respect other people's privacy. Messages from your group, and images/PDFs when enabled, are sent to Google's AI to be understood. Only use Maya on groups where that's okay, and never share the database file.

This is a personal tool, not for spam, marketing, or bulk messaging.

---

Quick start

You'll need Node.js 22 or newer (we develop on Node 24), a Gemini API key from Google AI Studio, and your phone with WhatsApp.

git clone https://github.com/Coding-Moves/maya-assistant.git
cd maya-assistant
npm install
cp .env.example .env

Open .env and add your Gemini key. Then:

npm run dev

On the first run, a QR code appears. On your phone, open WhatsApp → Settings → Linked devices → Link a device and scan it. The saved session reconnects on later runs without a new QR code.

Stop npm run dev before listing your group IDs; both commands use the same WhatsApp session:

npm run list-groups

Copy the IDs of the groups you want into GROUP_ALLOWLIST in .env and restart with npm run dev. Maya saves new text and captions from those groups, extracts tasks every EXTRACT_INTERVAL_MIN minutes, answers your commands and questions, and sends scheduled reminders while running.

To read JPEG, PNG, WebP, and PDF announcements, set MEDIA_ENABLED=true. Maya handles at most MEDIA_BATCH_SIZE files per extraction run and refuses files above MEDIA_MAX_BYTES (default 5 MB). Large files with a caption still contribute that caption. Media reading uses Gemini and can increase API usage. A failed item is retried three times, then quarantined and reported to you.

Google Calendar sync is optional. To enable it, follow the Calendar setup guide. Dated open tasks become Calendar events; changing a task updates its event, and completing or cancelling it removes the event. Sync runs with the extraction interval and retries failed requests. Task titles and details are sent to Google when enabled.

VU students can enable an optional daily check of only the assignment and quiz tables in Classic To Do, or continue using the manual CSV importer. Follow the VU setup guide. The automatic check requires private LMS credentials and a Chromium browser on the host; Maya does not read bell, notice-board, or GDB items.

For an always-on host, see the hosting guide. It covers the current systemd setup and optional PM2 or Docker deployments with persistent private storage.

To save a consistent SQLite snapshot while Maya is running, use npm run backup-db. It keeps the newest seven completed snapshots in data/backups/. These backups contain private group messages and tasks, so keep them private. Backups on the same disk do not protect against loss of the machine; off-machine backup automation is deferred.

Talking to Maya

On your own number: open the "Message Yourself" chat in WhatsApp. Start your message with her name, or mention @maya anywhere:

You write	What happens
@maya what's due tomorrow?	She answers
Hy @maya	She greets you
maya task or maya list	Lists all open tasks
maya tasks	Lists all open tasks
maya done 4 or maya complete 4	Marks task #4 as done
maya help or maya ?	Shows what she can do
buy milk	Ignored, it's your note

On a second number: save it as "Maya" in your contacts and message her directly. You can write done 4, hi, or ask a question without using her name first. She replies in plain text, shows typing while answering with AI, and marks your message read when she starts replying. Messages from other people are ignored.

You can also say “I've done it” or “ho gaya”. If one open task or a task you just discussed clearly matches, Maya ticks it off. If several could match, she asks you which one by name.

Don't like the name? Set BOT_NAME in .env to anything you want.

Settings

Everything lives in .env. The main ones:

Setting	What it does	Example
BOT_NAME	Her name, and the word that wakes her up in self mode	Maya
BOT_MODE	self = your own number, separate = second SIM	separate
OWNER_NAME	Optional name Maya uses occasionally in separate mode	Muawiya
GROUP_ALLOWLIST	Which groups she reads	1203...@g.us
TIMEZONE	Your timezone for reminders	Asia/Karachi
MORNING_DIGEST_CRON	When to send "due today"	0 8 * * *
EVENING_DIGEST_CRON	When to send "due tomorrow"	0 20 * * *
WEEKLY_PLAN_CRON	When to send the weekly plan	0 20 * * 5
GEMINI_MODEL	Which AI model to use	gemini-3.5-flash
MEDIA_ENABLED	Read supported group images and PDFs with Gemini	false
CALENDAR_SYNC	Sync dated open tasks with Google Calendar	false

The full list is in .env.example.

Switching to a second number later

1. Add the new number to your groups.
2. In .env, set BOT_MODE=separate and OWNER_JID=<your main number>@s.whatsapp.net.
3. Delete the auth_info/ folder.
4. Run npm run dev and scan the QR with the new phone.

In self mode, include Maya's name or @maya in messages you want her to handle. On a separate number, direct messages from the owner need no trigger.

What's coming

Maya is still experimental. See ROADMAP.md for what is implemented and what still needs a manual live check.

Use it, fork it, make it yours

Maya is a personal project, shared openly. I'm not accepting pull requests, but you're free to fork it, change it, and run your own version. If you build with AI coding agents, point them to AGENTS.md and ROADMAP.md. They have everything needed to build it step by step.

License

MIT. Use it, change it, share it.

---

Built by a student who missed one deadline too many.

Coding Moves Lab

Maya is a public-source experiment in Coding Moves Lab. The one-day reminder check and optional integrations need the owner's live validation.