A personal AI health coach that pulls your real Garmin data and lets you have a conversation with Claude about it. Ask about your sleep trends, recovery, training load, stress patterns — and get answers grounded in your actual numbers, not generic advice.
On startup, the app connects to your Garmin Connect account, fetches your health data, and opens a chat interface in your browser. Claude acts as your personal coach with full context of your metrics. The sidebar shows a live, structured view of your data while you chat.
Data fetched from Garmin Connect:
- Daily steps, total and active calories, distance
- Average and max stress levels, body battery
- Resting heart rate
- HRV — overnight average, weekly baseline, and status label (Balanced / Low / Unbalanced)
- Training Readiness — Garmin's 0–100 daily composite score (HRV + sleep + recovery + load)
- Training Status — rolling label (Productive, Peaking, Maintaining, Recovery, Strained, etc.)
- Sleep breakdown — total, deep, REM, light, and sleep score
- Recent activities — type, duration, distance, average HR, calories
- Body composition — weight, body fat %, and muscle mass from a smart scale
Nutrition data from MacroFactor:
- Daily calories, protein, carbs, fat, fiber, and alcohol
- TDEE (Total Daily Energy Expenditure) and trend weight
- Target macros from your MacroFactor programme
- Shown in a dedicated Nutrition tab in the sidebar; optionally included in Claude's context
What you can ask:
- "How has my sleep been this week?"
- "My stress has been high — what do you recommend?"
- "Am I recovering well enough to train hard tomorrow?"
- "Which day this week had my best body battery?"
- "My training status is Strained — should I take a rest day?"
- "How is my body composition trending over the past month?"
Claude maintains the full conversation history so follow-up questions work naturally.
You need two things before installing:
You almost certainly already have this if you own a Garmin device. It's the same account you use in the Garmin Connect app on your phone. If not, create one free at connect.garmin.com.
You'll need your Garmin email address and Garmin password.
This is what lets the app talk to Claude. It costs money to use, but for a single person chatting about their health data the cost is very small — typically a few cents per day of active use.
How to get one:
- Go to console.anthropic.com and create an account
- Click API Keys in the left sidebar
- Click Create Key, give it a name like "Garmin Coach", and copy the key
- Add a payment method under Billing — you only pay for what you use
The key looks like sk-ant-api03-... and is shown only once, so copy it somewhere safe.
There are two ways to install. Option A is recommended — no technical knowledge required.
No Python, no terminal, no setup. Just download and double-click.
Step 1 — Download
Go to the Releases page and download the file for your computer:
| Your computer | Download |
|---|---|
| Windows 10 or 11 | GarminHealthCoach-windows.zip |
| Mac (any model) | GarminHealthCoach.dmg |
Step 2 — Install
On Windows:
- Right-click the downloaded
.zipfile and choose Extract All - Open the extracted folder called
GarminHealthCoach - Double-click
GarminHealthCoach.exeto launch
On Mac:
- Double-click the downloaded
.dmgfile - Drag
Garmin Health Coachinto your Applications folder - Open your Applications folder and double-click
Garmin Health Coach
Mac security note: The first time you open the app, macOS may say it "can't be verified". This happens with apps that aren't from the App Store. To allow it: go to System Settings → Privacy & Security, scroll down, and click Open Anyway.
Step 3 — First launch
When you launch the app:
- A small icon appears in your system tray (bottom-right on Windows, top-right menu bar on Mac)
- Your browser opens automatically to the Settings page
- Enter your Garmin email, Garmin password, and Anthropic API key
- Click Save & Connect
The app will connect to Garmin, fetch your data, and open the chat. This takes about 10–20 seconds on first run.
From now on, just double-click the app icon. Your credentials are saved securely in your OS keychain — you'll never be asked for them again unless you change your password.
To close the app, right-click the tray icon and choose Quit. Closing the browser tab does not stop the app.
This option requires Python installed on your computer and comfort with the terminal.
Step 1 — Install Python
Download Python 3.10 or higher from python.org. During installation on Windows, check the box that says "Add Python to PATH".
Step 2 — Download the code
git clone https://github.com/duvalcyril/Claude4Garmin.git
cd Claude4GarminOr download the ZIP from GitHub and extract it.
Step 3 — Create a virtual environment
python -m venv .venvActivate it:
- Windows (PowerShell):
.\.venv\Scripts\Activate.ps1 - Windows (Command Prompt):
.\.venv\Scripts\activate.bat - macOS / Linux:
source .venv/bin/activate
Step 4 — Install dependencies
pip install -r requirements.txtStep 5 — Launch the app
python launcher.pyThe app starts, a tray icon appears, and your browser opens. On first launch you'll be taken to Settings to enter your credentials.
You can also run the web server directly (no tray icon, browser opens automatically):
python server.pyType any question about your health data in the chat box and press Enter. Claude has full context of your Garmin data and will give you specific, personalised answers based on your actual numbers.
The sidebar on the left shows your current data — training status, daily stats, sleep, recent activities, and body composition.
| Button | What it does |
|---|---|
| Refresh data | Re-fetch your latest Garmin data without restarting |
| Reset conversation | Clear the chat history and start fresh (your data stays loaded) |
| Settings | Update credentials, change what data is synced, manage skills |
Type / in the chat input to open a menu of coaching shortcuts. Two types are available:
- Prompt skills — pre-written prompts that expand into the text box, ready for you to review and send. Good for weekly summaries or training plan requests.
- Personas — activate a coaching personality that changes Claude's style and focus for the whole conversation. A badge shows the active persona; click × to deactivate.
You can upload your own skills and personas from Settings → Skills & Personas.
Go to Settings (gear icon or the Settings button) to configure the app.
Update your Garmin email, password, or Anthropic API key. You only need to do this if you change your password or want to use a different API key.
Tell Claude who you are. This is the most impactful thing you can set up — it's injected into every conversation and your daily digest so Claude responds with your goals and context in mind, not just raw numbers.
Fields you can fill in:
- Your name — Claude will address you by name in every response and in the digest
- Sport(s) — what you train for (e.g. Running, Cycling, Triathlon)
- Level — Recreational / Competitive amateur / Serious competitive / Professional
- Current goal — in your own words (e.g. "Sub-3:30 marathon at Paris in April, also trying to lose 3–4 kg")
- Training days per week and Training plan (optional)
- Upcoming events — races or goals with dates (optional)
- Health notes — injuries, limitations, or anything your coach should know (optional)
The profile is saved immediately and takes effect from your next message — no restart needed.
Choose what data the app fetches and how far back it looks:
- Time range — 7, 14, or 30 days of history
- Daily Stats — steps, calories, stress, body battery, resting HR, distance
- Sleep — total duration, deep, REM, light sleep, sleep score
- Activities — toggle on/off, choose how many recent activities to show (5, 10, or 20)
- HRV — overnight HRV average and status shown alongside daily stats
- Training Readiness — 0–100 score shown alongside daily stats
- Training Status — rolling label shown in the sidebar header
- Body Composition — weight, body fat %, muscle mass (requires a Garmin-compatible smart scale)
Changes take effect immediately — the app re-fetches your data after saving.
Import your food log data from MacroFactor to give Claude full context across training, recovery, and fueling.
Importing MacroFactor data:
- Open the MacroFactor app and go to Profile → Export Data → Quick Export
- Choose Daily Summary export and select your desired date range
- Save or share the CSV file to your computer
- In the app, go to Settings → Nutrition and drag the CSV into the upload area
- The Nutrition tab in the sidebar will populate with your macro data
For detailed export instructions see the MacroFactor user guide.
AI Context controls (under Settings → Nutrition → AI Context):
- Include daily macro totals — sends your daily calorie and macro breakdown to Claude (low token cost)
- Include full food log — sends individual food entries; toggle off to reduce token usage if costs are a concern
Upload .json prompt skills or .skill persona files by dragging them into the upload area.
Set up a morning email with yesterday's key stats and a short coaching summary from Claude. See the Daily Digest section below.
Get a morning email every day with yesterday's key stats and a Claude-generated coaching take — no need to open the app.
What's in the digest:
- Steps, calories, body battery, resting HR
- HRV (overnight average + status), Training Readiness score, Training Status label
- Sleep breakdown — total, deep, REM, score
- A personalised coaching paragraph from Claude: references your specific numbers, explains what they mean for how you should train or recover today, and ends with one concrete actionable suggestion. If you've filled in your athlete profile, Claude will address you by name and factor in your goals and training context.
- A daily motivational quote chosen to fit your current situation (recovery-themed if readiness is low, performance-themed if you're in a productive phase)
Setup (in Settings → Daily Digest):
- Enter your recipient email address and preferred send time
- Enter a Gmail address to send from
- Enter a Gmail App Password — this is not your regular Gmail password. To generate one:
- Go to myaccount.google.com/apppasswords
- You must have 2-Step Verification enabled on your Google account first
- Select Mail as the app and your device, then click Generate
- Copy the 16-character password shown
- Click Save Digest Settings
- Click Send Test to make sure everything works before the first scheduled send
Note: The digest is currently only supported on Windows — it uses Windows Task Scheduler to send the email at the scheduled time. Mac support is planned.
Errors are logged to digest.log in %APPDATA%\GarminHealthCoach\ (packaged app) or the project folder (running from source).
Your Garmin email/password and Anthropic API key are stored in your OS keychain — Windows Credential Manager on Windows, Keychain Access on macOS. They are never written to any file on disk.
Your other settings (which metrics to show, date range, etc.) are saved in a file called settings.json:
- Packaged app (Option A):
%APPDATA%\GarminHealthCoach\settings.jsonon Windows,~/Library/Application Support/GarminHealthCoach/settings.jsonon macOS - Running from source (Option B):
settings.jsonin the project folder
If your Garmin account has 2FA enabled, you'll be prompted to enter your code the first time you log in. After that, the app saves a session token so you won't be asked again until the session expires (usually several weeks).
Your Garmin credentials are incorrect. Go to Settings → Connection and re-enter them. Make sure you're using the email and password for connect.garmin.com, not your Garmin device PIN.
Your API key may be invalid or have no credits. Check at console.anthropic.com that the key is active and your account has a payment method. Go to Settings → Connection to update the key.
Not all Garmin devices record all metrics. Fields the app can't find are shown as — in the sidebar and are silently omitted from Claude's context — they don't cause errors. Body composition data requires a Garmin-compatible smart scale.
If Garmin login fails despite correct credentials, the saved session token may have expired. Delete the session folder and the app will log in fresh:
- Packaged app:
- Windows: delete
%APPDATA%\GarminHealthCoach\.garth_session - macOS: delete
~/Library/Application Support/GarminHealthCoach/.garth_session
- Windows: delete
- Running from source: delete the
.garth_sessionfolder in the project directory
macOS quarantines apps downloaded from the internet that aren't from the App Store. The fastest fix is to run this command in Terminal after moving the app to your Applications folder:
xattr -cr /Applications/GarminHealthCoach.appThis strips the quarantine flag and the app will open normally from then on. No need to re-run it after updates — just repeat the command for each new version you download.
If you'd prefer not to use Terminal, the manual alternative is: System Settings → Privacy & Security, scroll to the bottom, and click Open Anyway next to the Garmin Health Coach entry.
Click Send Test in Settings → Daily Digest to see the error. Common causes:
- Gmail App Password not set up (2-Step Verification must be enabled first)
- Recipient email address is missing
- On Windows: the Task Scheduler task wasn't registered (try saving Digest Settings again)
Check digest.log for the full error message. On the packaged app it's in %APPDATA%\GarminHealthCoach\digest.log.
If you see a tray icon but the browser doesn't open, click the tray icon and choose Open Garmin Health Coach. If you launched the app twice, the second launch will just open the browser — only one instance runs at a time.
garmin-health-coach/
├── launcher.py # Desktop entry point — tray icon, server thread, browser open
├── server.py # FastAPI web server — all routes and API endpoints
├── main.py # CLI entry point — terminal chat loop (no browser)
├── paths.py # Path resolution for dev vs. packaged (PyInstaller) modes
├── digest.py # Standalone daily digest emailer (Windows Task Scheduler)
├── garmin_client.py # Garmin Connect auth, data fetching, formatting
├── claude_client.py # Claude API wrapper with streaming, history, personas
├── credentials_manager.py # OS keychain read/write via the keyring library
├── settings_manager.py # Data sync preferences stored in settings.json
├── skills_manager.py # Loads prompt skills (.json) and personas (.skill)
├── data_cache.py # Incremental Garmin data cache (avoids re-fetching old data)
├── nutrition_parser.py # MacroFactor CSV parser and nutrition data persistence
├── setup_ui.py # Interactive credential setup wizard for CLI mode
├── templates/
│ ├── index.html # Main chat UI — split panel with sidebar + chat
│ ├── settings.html # Settings page — credentials, data prefs, skills, digest
│ └── digest_email.html # HTML email template for the daily digest
├── static/
│ ├── style.css # App styles
│ └── app.js # SSE streaming, chat logic, skill picker
├── assets/
│ ├── icon.png # App icon (512×512 PNG)
│ ├── icon.ico # Windows icon
│ └── icon.icns # macOS icon
├── garmin_coach.spec # PyInstaller build specification
├── build_windows.bat # Windows build script → GarminHealthCoach-windows.zip
├── build_macos.sh # macOS build script → GarminHealthCoach.dmg
├── .github/
│ └── workflows/
│ └── release.yml # GitHub Actions: build both platforms on tag push
├── requirements.txt
├── .env.example # Reference for environment variable names
├── .gitignore
└── ROADMAP.md
OS keychain → environment variables → .env file
You can also pass credentials as environment variables (useful for scripting):
GARMIN_EMAIL=you@example.com GARMIN_PASSWORD=secret ANTHROPIC_API_KEY=sk-ant-... python server.pyWindows:
build_windows.batOutput: dist\GarminHealthCoach\GarminHealthCoach.exe and GarminHealthCoach-windows.zip
macOS:
chmod +x build_macos.sh
./build_macos.shOutput: dist/GarminHealthCoach.app and GarminHealthCoach.dmg
Automated releases via GitHub Actions:
Push a tag in the format v1.0.0 and GitHub will automatically build both platforms and attach the files to a GitHub Release.
git tag v1.0.0
git push origin v1.0.0See ROADMAP.md for the full list. The main planned additions are:
HR time-in-zones — Zone breakdown per activity (Z1–Z5 minutes) so Claude can analyse aerobic vs. anaerobic distribution and flag if easy runs are drifting out of Zone 2.
Race predictions & Cycling FTP — Garmin's estimated race times (5k–marathon) and functional threshold power for deeper performance context.
Custom workout creation — Generate personalised running and cycling workouts tailored to your current fitness level and goals, then upload them directly to Garmin Connect so they appear on your device.
Trend alerts — Flag when a metric crosses a threshold (e.g. resting HR up 5+ bpm for 3 consecutive days, sleep score below 60 two nights in a row).
macOS Daily Digest — Scheduled digest emails via launchd (macOS equivalent of Task Scheduler).
| Package | Purpose |
|---|---|
garminconnect |
Garmin Connect API client |
anthropic |
Claude API client (sync + async) |
fastapi |
Web framework for the browser UI |
uvicorn |
ASGI server that runs FastAPI |
jinja2 |
HTML templating for server-rendered pages |
python-multipart |
Form data parsing for FastAPI |
keyring |
Secure OS keychain storage |
pystray |
System tray icon (cross-platform) |
Pillow |
Image handling for the tray icon |
rich |
Terminal formatting for the CLI setup wizard |
python-dotenv |
Optional .env file fallback |