🎯 The problem: generic advice × your data
Ask a regular chatbot "should I drink coffee now?" and it replies with a internet average: “avoid after 2 p.m.” The answer is the same for everyone—it doesn’t know how you slept, what time it is for your body, or how you metabolize caffeine. HealthOS replaces that average with an answer grounded in you.
✗ Generic advice
- ✗"Sleep 8 hours" — without knowing how much YOU slept last night.
- ✗"Eat less salt" — without seeing your blood pressure rise 10-15% after a salty lunch.
- ✗It forgets everything in the next conversation. No memory, no pattern.
✓ Coaching with your data
- ✓"Recovery 48% today — yesterday’s wine probably took a toll. Take it easy."
- ✓"You metabolize caffeine quickly (CYP1A2): coffee early, cut it off in the afternoon."
- ✓Remembers weeks ago: "every time you eat dinner late, your sleep suffers".
💡 The idea in one sentence
Specific beats generic. A coach grounded in your labs, genetics, and goals gives advice mechanism-aware (you know the “why” in your body); a generic bot offers platitudes. The entire HealthOS design forces this specificity.
Key concepts
A response grounded in your numbers, not the average.
Remembers your history and sees patterns over the course of weeks.
Explain the cause in your body, not just the recommendation.
Wearable + blood + DNA + diet, together.
🫀 What exactly is HealthOS
HealthOS is a complete blueprint (a model project, ready to clone) for a personal health coach that lives in a Telegram bot. You talk to it by message; behind the scenes, it stores everything in a database just for you, reads your wearable, and always responds based on your current context.
🟢 New here? Three words before you continue
- LLM — is the kind of AI model that runs behind ChatGPT/Claude. It’s the “brain” that reads your data and writes the response.
- Coach (agent) — this isn’t just a chat: it’s a agent, a program that acts on its own (fetches your data, writes to the database, triggers the morning review) in addition to chatting.
- Mechanism-aware — “mechanism-aware”: instead of just telling you to “drink less coffee,” it knows the physiological reason in YOU (e.g., your caffeine gene) and acts on it.
📦 What’s included
- •One coach on Telegram grounded in your data, not generic advice.
- •One own database (Supabase) with food, workouts, weight, caffeine, supplements, vital signs, lab results, check-ins, and goals — plus message memory.
- •A wearable connection (WHOOP in the example) end to end: authorization, daily sync, and data mapping.
- •A recovery-guided morning review and a dashboard with the trends.
🧭 Where it runs
You point your Claude Code or Codex to the repository and builds yours. The example uses WHOOP, but any source works (Apple Watch, Garmin, or manual logging) — the coach works with whatever reaches the database. The author ran this live for 15+ days before publishing.
Key concepts
Template project ready to clone and customize.
The interface: you talk through messages.
Your data in your own private Supabase.
Acts on its own, not just responds.
🧩 The 4 data sources
The coach’s strength comes from cross-reference four sources that usually live in separate apps. On its own, each is one piece; together, they provide context. The diagram below shows all four converging into a single coach.
📊 How to read: the four sources (cyan, on the left) feed into the coach, which combines them and returns specific advice (green). No source alone would be enough — the value lies in the cross-referencing.
⌚ Wearable
Recovery, heart rate variability, resting heart rate, and hours of sleep. It’s “how your body woke up today.”
🩸 Blood
Markers such as ApoB, HOMA-IR, vitamin D. The biochemical snapshot of your metabolism and risk.
🧬 DNA
SNPs (genetic variations) that adjust dosages: caffeine, saturated fat, vitamin D, salt. Genes as buttons.
🍽️ Diet
Food photo → macros estimated by vision. Closes the loop between what you eat and how you recover.
Key concepts
How your body woke up today.
The biochemistry of metabolism.
Adjusts dosages — genes as switches.
The value comes from bringing all four together.
🏗️ High-level architecture
Every time you send a message, the same sequence happens: the agent reads a snapshot (a compact summary of your current state) from the database, reasons with the LLM grounded in your data, and responds. Follow the flow in the diagram.
🟢 New here?
- Supabase — is a cloud database (PostgreSQL) with file storage. It’s where ALL your health data lives, in a private project just for you.
- Session snapshot — a compact snapshot of “right now”: weight trend, what you ate today, blood pressure, yesterday’s recovery, the 7-day sleep pattern, and your goals. The agent reads this at the start of every conversation so it can always respond with current context.
📊 How to read: from left to right is the path of the question; the dashed line is the answer coming back. The agent never "guesses": it always reads the database snapshot before reasoning.
🧠 Memory is the product
Everything is written to the database as structured rows. That's why the coach knows your entire history and can spot patterns over weeks — it doesn't just react to the latest message. We cover these modules in detail in Track 1 (signals and memory) and Track 2 (the database).
Key concepts
A compact snapshot of "now," read at every turn.
Orchestrator: reads, reasons, writes, responds.
The private database where everything is recorded.
Structured lines = patterns over time.
🌅 A day in the life of a coach
The whole day happens in Telegram. The example below is illustrative (fictional numbers, not advice) — shows how the loop closes: today’s choice becomes tomorrow’s recovery.
📊 How to read: today's recovery starts the day; your choices are recorded; tomorrow's recovery reflects those choices. This cycle is the backbone of HealthOS — it teaches you your own buttons.
food_log)Key concepts
The morning number determines whether to push or rest.
Today’s choice becomes tomorrow’s recovery.
Each choice becomes a row in the database.
You learn what affects your body.
🔒 Privacy and security
Health data is sensitive. HealthOS is locked by default: private project, server-side access, secrets kept out of git. Nothing leaves except the LLM calls you choose to make.
🟢 New here?
RLS (Row-Level Security) — “row-level security.” It’s a database feature that decides who can read each row. In HealthOS, RLS stays enabled without any policy: the public (anon) key can’t read anything, and only the server (with the service-role key) can access it. Result: no one outside can read your data.
✓ What the design guarantees
- ✓Supabase project private, in your account.
- ✓RLS enabled, no policies: the anon key can’t read anything.
- ✓Secrets in
~/.env(your home directory), never in git.
✗ What to never version-control
- ✗Your
CLAUDE.mdfilled in (real profile). - ✗The seed's actual values and your photos.
- ✗The file
~/.envwith the keys.
Key concepts
The database is yours, in your account.
No one outside can read your entries.
In ~/.env, outside version control.
Nothing goes out beyond what you choose.
⚠️ Not medical advice · cost and prerequisites
Before anything technical, the most important rule in the entire course: this is a tool for logging and reasoning, not a doctor.
⚠️ Not medical advice
- •It’s the example of a person, who consulted doctors at every step. This is not a prescription for you.
- •AI can hallucinate. Treat every suggestion as a question to discuss with your doctor, never as an order.
- •The coach is instructed to no diagnose or change medication; it refers you to a clinician.
- •DNA samples mailed in degrade — the clinic’s panel and Ancestry’s may not match.
💰 How much it costs to run
- Supabase — the free plan is enough for one person.
- LLM + embeddings — the calls you make (cents for embeddings; ~US$10-20/month for typical usage).
- Vision (Gemini) — cents per photo.
- WHOOP — the API is free with the subscription. Don’t have WHOOP? Use another wearable or manual logging.
🧰 What you’ll need (overview)
Python 3.9+, Node, a Supabase account, a Telegram bot, and API keys (OpenAI, Gemini, optionally WHOOP). Don’t worry about having everything now — the Track 2 (Step by step) builds each piece with you, from scratch.
Key concepts
Have a clinician verify everything.
Free tier + ~US$10-20/month.
Any source works.
The prerequisites are covered in the step-by-step instructions.
✅ Self-check (optional): what makes HealthOS different from a regular chatbot?
📋 Module summary
Next module:
1.2 — Body signals: recovery, HRV, RHR, sleep, and the blood markers your coach reads.