v3.3.8 — Hardened installer + Android one-tap setup

Study smarter.
Own your data.

IsotopeAI is a self-hosted study planner for JEE, NEET, and Board students. It runs on your own device — phone, laptop, or desktop — with optional Supabase cloud sync. No subscription. No vendor lock-in.

⚡ Install now 📱 Android (one command) View on GitHub
IsotopeAI dashboard — daily stats, focus timer, streaks
✅ App runs locally — no cloud server needed ✅ CI-tested installer on every commit ✅ Supabase free tier works ✅ PWA — works offline after first load ✅ Android Termux supported ✅ MIT licensed
Why it exists

Study tracking without SaaS lock-in

Most study apps are SaaS products. You log your data into someone else's server, pay a monthly fee, and lose everything if you stop paying. IsotopeAI runs entirely on your device. Supabase is optional — it only provides sync, auth, and community. Stop paying for Supabase? Export your data and keep studying locally.

🖥️

Runs on your device

Start the Node.js server, open localhost:3000, and the entire app runs locally. No data ever touches a server you don't own.

📶

Offline-capable PWA

After first launch the service worker caches the app shell. You can study, use the timer, and view analytics without internet — server-side features show honest offline status.

☁️

Supabase sync — optional

Point the app at your own free Supabase project for auth, realtime community, and cloud backup. Run the SQL schema once and you're done.

📱

Android phone server

Run IsotopeAI entirely on an Android phone via Termux. One install command, then home-screen widget buttons for start, update, and open.

🔐

Your Supabase, your data

The Supabase project is yours — you create it, own the credentials, and can export or delete all data at any time. IsotopeAI never has access to it.

⚡

No VPS required

This is not a self-hosted SaaS. There is no server to provision, configure, or maintain. The app is a Node.js process on your own machine.

Features

Everything a serious student needs

Built specifically for competitive exam prep — not generic productivity.

⏱️

Focus Timer

  • Pomodoro and custom session modes
  • Subject and task tagging per session
  • Session log with every minute tracked
  • Streak counter and daily goals
📊

Analytics

  • Hourly, daily, weekly time breakdowns
  • Per-subject and per-chapter distribution
  • Habit consistency scoring
  • AI weekly summary cards
📚

Syllabus & Exams

  • Chapter-by-chapter syllabus with progress bars
  • Exam countdown calendar
  • Mock test tracker and result log
  • Mistake journal
✅

Task Planner

  • Priority levels, due dates, subtasks
  • Subject-linked tasks
  • Daily habit tracker
  • Filters and sort by urgency
👥

Community

  • Study groups with real-time leaderboards
  • Group chat with live presence
  • Group and global challenges
  • One-click invite links
🤖

AI (optional)

  • AI weekly study summary
  • Configure with Gemini or Groq API key
  • Runs entirely through your local server
  • Not required to use the app
Install

Get running in under 60 seconds

You need Node.js 18+ and a free Supabase project for auth and sync. For local-only testing, you can start the server immediately and skip Supabase.

Step 1: Install Termux from F-Droid or GitHub Releases — not the Play Store.

Step 2: Open Termux and paste this one command: 

bash <(curl -fsSL https://raw.githubusercontent.com/Suydev/isotope-code/main/install-termux.sh)

Step 3: After install, use home-screen widget buttons — no typing needed.

⚠️ Install Termux:Widget from the same source as Termux (F-Droid or GitHub). Mixing sources causes install failures. See TERMUX_WIDGET.md for full details. 
git clone https://github.com/Suydev/isotope-code.git
cd isotope-code
bash setup.sh

setup.sh automatically installs Node.js 22 via NodeSource on Ubuntu/Debian if not present. After setup, open http://127.0.0.1:3000.

CMD or PowerShell:

git clone https://github.com/Suydev/isotope-code.git
cd isotope-code
setup.bat

PowerShell (automated Node install):

git clone https://github.com/Suydev/isotope-code.git
cd isotope-code
.\install.ps1
# From any directory after setup
isotope update

Stashes local changes → fetches latest → fast-forward merges → runs npm install if needed → restarts server. On Android, automatically refreshes widget shortcuts too. 

# Windows
update.bat
After install — CLI commands
isotope start              # start server in background
isotope stop               # stop server
isotope restart            # stop + start + open
isotope update             # pull latest version
isotope status             # show PID, port, version, config
isotope doctor             # full diagnostic — checks everything
isotope open               # open in browser
isotope logs               # last 80 log lines (secrets redacted)
isotope repair             # fix broken deps or CLI
Supabase

Set up your cloud backend in 5 minutes

Required for auth, community, and cross-device sync. The free Supabase tier works indefinitely for personal use.

1️⃣
Create a free project at supabase.com — takes 2 minutes.
2️⃣
In your Supabase dashboard, go to SQL Editor → paste and run isotope-complete.sql from the repo. Creates all 24 tables, RLS policies, triggers, storage buckets, and seed data in one shot.
3️⃣
Copy your Project URL and anon/public key from Project Settings → API.
4️⃣
Paste them into .env:

SUPABASE_URL=https://your-ref.supabase.co
SUPABASE_ANON_KEY=your-anon-key
🔐 Never share or commit your SUPABASE_SERVICE_ROLE_KEY. Normal users only need the anon key. The service-role key grants unrestricted database access.
Architecture

How it works

Three layers. You own all of them. No intermediary server.

┌──────────────────────────────────────────────────────────────┐ │ Your Browser / PWA │ │ React + Zustand + React Query + Service Worker │ └───────────────────────┬──────────────────────────────────────┘ │ http://localhost:3000 ┌───────────────────────▼──────────────────────────────────────┐ │ Local Node.js Server │ │ server.mjs — Express 5 + JWT verification + Supabase proxy │ │ Routes: /__auth/* /__admin/* /api/* /__supa/* │ └───────────────────────┬──────────────────────────────────────┘ │ REST / Realtime / Storage (optional) ┌───────────────────────▼──────────────────────────────────────┐ │ Supabase (your own free project) │ │ PostgreSQL · Auth · Storage · Realtime · Edge Functions │ │ 24 tables · RLS · Triggers · 3 buckets · 30+ functions │ └──────────────────────────────────────────────────────────────┘
🌐

Browser / PWA

The React app is compiled to static files and served by your local Node.js server. The service worker enables offline use after the first visit.

⚙️

Local Node.js server

Runs on your device. Proxies auth and database requests to Supabase, adds JWT verification, and serves the compiled frontend. The only process you run.

🗄️

Supabase

Acts as a cloud database, auth provider, and storage backend — only if you connect it. IsotopeAI is designed to gracefully handle offline or unconfigured Supabase.

Reliability

Tested on every commit

CI runs against every push to main. Install scripts are syntax-checked, shell-linted, and smoke-tested against a real Node.js server start.

✅
Shell syntax check — bash -n on all 7 shell scripts on every CI run
✅
ShellCheck lint — all install/setup scripts are linted with ShellCheck
✅
Required files check — 19 critical files verified present on every build
✅
Smoke test — server starts and responds to /api/health using safe placeholder credentials
✅
Release zip validation — zip is built and extracted to confirm all required files are present
✅
Termux simulation — platform detection tested with TERMUX_VERSION=ci-test
✅
No hardcoded secrets — grep scan for service-role key patterns in all source files
✅
Docs validation — screenshot paths, image links, and install command references verified
FAQ

Common questions

Is this a hosted service?
No. IsotopeAI is software you download and run yourself. There is no cloud server, no account at isotopeai.in, and no third-party service that holds your study data. It's a Node.js app that runs on your device.
Do I need Supabase?
Only for auth, community features, and cross-device sync. The timer, local analytics, tasks, syllabus, and habits work without Supabase. You'll need to provide a Supabase URL and anon key in .env for the app to fully function.
Does it work offline?
Yes — partially. The service worker caches the app shell after the first load. If the local Node.js server is running, the full app works without internet. If the server is also off, the PWA shell loads from cache but shows honest offline status for server-dependent features.
Can I run it on Android?
Yes. Termux runs Node.js on Android without root. One install command sets everything up, and Termux:Widget home-screen buttons let you start, stop, update, and open the app without typing. Works on phones with 2GB+ RAM.
Is my study data private?
Yes. Your data lives in your local Node.js process and your own Supabase project. IsotopeAI's author has no access to either. Secrets stay in your .env file on your device.
Why a local server and not a browser extension or static app?
A local Node.js server can proxy Supabase auth and database requests, manage sessions securely, serve the service worker correctly, and run background sync tasks. A pure browser app would expose Supabase credentials in JavaScript and lose control over session management.
How do I update?
Run isotope update from any directory, or tap the isotope-update widget on Android. It stashes local changes, pulls the latest commit, reinstalls dependencies if needed, and restarts the server — all without touching your .env.
Something broke. How do I fix it?
Run isotope doctor — it checks Node.js, Git, PATH, Supabase config, PWA files, server health, and (on Android) Termux tools and widget shortcuts. For deeper issues, run isotope repair to re-install dependencies and refresh the CLI.