Trail map
Detailed content
2.1~35 min
🧰 Prerequisites and accounts
The mise en place: what to install, the accounts (Supabase, Telegram, OpenAI/Gemini, WHOOP), and the ~/.env with all the keys in place before coding.
Progress0 of 7 · 0%
What is: The core tools on the machine: Python 3, git, and the agent CLI (Claude Code).
Why learn: Without the environment ready, none of the commands in the next steps will run.
Key concepts: Python 3 · git · venv.
What is: Create a free Supabase project, which provides ready-to-use Postgres + storage.
Why learn: It’s the database where all your health data will live.
Key concepts: Project · URL · service-role key.
What is: Talk to @BotFather to create the bot and get the access token.
Why learn: Telegram is the coach’s interface; without a token, there’s no bot.
Key concepts: BotFather · token · chat_id.
What is: The API keys for the language model and embedding generator.
Why learn: It’s the agent’s “brain” and semantic memory.
Key concepts: API key · embeddings · quota.
What is: Create an app in the WHOOP developer portal to get a client ID and secret.
Why learn: It’s what lets you automatically pull recovery and HRV (it’s optional).
Key concepts: Client id · secret · OAuth.
What is: A single file, outside the repo, that holds all the secrets.
Why learn: Centralizes the keys and keeps them out of git.
Key concepts: ~/.env · gitignore · secrets.
What is: The list confirming that every account and every key already exists.
Why learn: Fetches what's missing now, before you get stuck halfway through the step.
Key concepts: Accounts · keys · environment.
2.2~35 min
🗄️ The database (Supabase)
The 14 tables, pgvector for memory, the storage bucket, and the RLS that locks everything down. You run the migrations and check the connection.
Progress0 of 7 · 0%
What is: Apply the SQL files that create all tables at once.
Why learn: It’s how the database goes from zero to the complete schema.
Key concepts: SQL · migration · idempotent.
What is: The 14 tables that store wearable, blood, DNA, diet, and memory data.
Why learn: Knowing where each piece of data lives helps you query and debug.
Key concepts: Schema · relationships · keys.
What is: The Postgres extension that stores embeddings and searches by similarity.
Why learn: It’s what gives the coach semantic memory.
Key concepts: Extension · vector · similarity.
What is: The bucket where food photos and exam PDFs are stored.
Why learn: The agent needs a place for the raw files.
Key concepts: Bucket · upload · signed URL.
What is: Rules that lock each row so only its owner can read it.
Why learn: Health data is sensitive; RLS is the default lock.
Key concepts: Policy · owner · private.
What is: Run a ping on the database to confirm that everything connects end to end.
Why learn: Confirms credentials and network before you keep building.
Key concepts: Connection · service-role · ping.
What is: Enter some sample data and your initial profile.
Why learn: Gives the coach something to read from day one—with privacy in mind.
Key concepts: Seed · profile · care.
2.3~35 min
🤖 The agent and the bot
agent.yaml, CLAUDE.md with your profile, slash commands, starting the bot, and how state.py and mem.py provide context and memory for each turn.
Progress0 of 7 · 0%
What is: The file that defines the agent’s model, tools, and parameters.
Why learn: It’s the control panel for how the agent runs.
Key concepts: Config · model · tools.
What is: The text with your goals, constraints, and the coach’s style.
Why learn: That’s where personalization really lives.
Key concepts: Profile · goals · style.
What is: Telegram shortcuts that trigger specific coach routines.
Why learn: Make common actions fast and consistent.
Key concepts: Command · routine · shortcut.
What is: Run the process that connects the agent to Telegram and keeps listening.
Why learn: It’s the moment when the coach comes alive and responds.
Key concepts: Polling · process · log.
What is: The code that builds a compact snapshot of the current state on each turn.
Why learn: It’s what keeps the coach grounded in today’s context.
Key concepts: Snapshot · context · turn.
What is: The embedding search that brings back relevant memories.
Why learn: Helps the coach remember your old patterns.
Key concepts: Recall · embedding · top-k.
What is: The agent's folder and file map (scripts, config, modules).
Why learn: Knowing the structure speeds up any change you make.
Key concepts: Folders · scripts · modules.
2.4~35 min
⌚ Wearable and scheduling
WHOOP end to end: OAuth, the one-time authorization, whoop-sync.py, the two classic gotchas, and how to schedule the sync and morning check-in.
Progress0 of 7 · 0%
What is: The flow that exchanges your login for a WHOOP access token.
Why learn: It’s the gateway for pulling your recovery data.
Key concepts: OAuth · token · refresh.
What is: The manual step you do just once in the browser.
Why learn: After that, sync runs automatically.
Key concepts: Consent · callback · code.
What is: The script that downloads recovery, sleep, and HRV into the database.
Why learn: It’s what fills the database with the day’s data.
Key concepts: Sync · upsert · API.
What is: The two common pitfalls: an expired token and the wrong time zone.
Why learn: Knowing about them beforehand saves hours of debugging.
Key concepts: Refresh · UTC · timezone.
What is: A cron job that runs whoop-sync.py every day early in the morning.
Why learn: Ensures fresh data before the morning check-in.
Key concepts: Cron · scheduling · log.
What is: The job that sends the coach's good morning message with your recovery score.
Why learn: It’s the trigger for the daily recovery loop.
Key concepts: Cron · check-in · push.
What is: How to adapt the same sync pattern for Oura, Garmin, or Apple Health.
Why learn: The blueprint isn’t tied to WHOOP.
Key concepts: Adapt · API · upsert.