{"skill":{"slug":"garmin-health-analysis","displayName":"Garmin Health Analysis","summary":"Talk to your Garmin data naturally - \"what was my fastest speed snowboarding?\", \"how did I sleep last night?\", \"what was my heart rate at 3pm?\". Access 20+ metrics (sleep stages, Body Battery, HRV, VO2 max, training readiness, body composition, SPO2), download FIT/GPX files for route analysis, query elevation/pace at any point, and generate interactive health dashboards. From casual \"show me this week's workouts\" to deep \"analyze my recovery vs training load\".","description":"---\nname: garmin-health-analysis\ndescription: Talk to your Garmin data naturally - \"what was my fastest speed snowboarding?\", \"how did I sleep last night?\", \"what was my heart rate at 3pm?\". Access 20+ metrics (sleep stages, Body Battery, HRV, VO2 max, training readiness, body composition, SPO2), download FIT/GPX files for route analysis, query elevation/pace at any point, and generate interactive health dashboards. From casual \"show me this week's workouts\" to deep \"analyze my recovery vs training load\".\nversion: 1.2.2\nauthor: EversonL & Claude\nhomepage: https://github.com/eversonl/ClawdBot-garmin-health-analysis\nmetadata: {\"clawdbot\":{\"emoji\":\"⌚\",\"requires\":{\"env\":[\"GARMIN_EMAIL\",\"GARMIN_PASSWORD\"]},\"install\":[{\"id\":\"garminconnect\",\"kind\":\"python\",\"package\":\"garminconnect\",\"label\":\"Install garminconnect (pip)\"},{\"id\":\"fitparse\",\"kind\":\"python\",\"package\":\"fitparse\",\"label\":\"Install fitparse (pip)\"},{\"id\":\"gpxpy\",\"kind\":\"python\",\"package\":\"gpxpy\",\"label\":\"Install gpxpy (pip)\"}]}}\n---\n\n# Garmin Health Analysis\n\nQuery health metrics from Garmin Connect and generate interactive HTML charts.\n\n## Two Installation Paths\n\nThis skill supports **two different setups**:\n\n1. **Clawdbot Skill** (this guide) - Use with Clawdbot for automation and proactive health monitoring\n2. **MCP Server** ([see MCP setup guide](references/mcp_setup.md)) - Use with standard Claude Desktop as an MCP server\n\nChoose the path that matches your use case. You can also use both simultaneously!\n\n---\n\n## Clawdbot Skill Setup (first time only)\n\n### 1. Install Dependencies\n\n```bash\npip3 install garminconnect\n```\n\n### 2. Configure Credentials\n\nYou have three options to provide your Garmin Connect credentials:\n\n#### Option A: Clawdbot Config (Recommended - UI configurable)\n\nAdd credentials to `~/.clawdbot/clawdbot.json`:\n\n```json\n{\n  \"skills\": {\n    \"entries\": {\n      \"garmin-health-analysis\": {\n        \"enabled\": true,\n        \"env\": {\n          \"GARMIN_EMAIL\": \"your-email@example.com\",\n          \"GARMIN_PASSWORD\": \"your-password\"\n        }\n      }\n    }\n  }\n}\n```\n\n**Tip**: You can also set these through the Clawdbot UI in the Skills settings panel.\n\n#### Option B: Local Config File\n\nCreate a config file in the skill directory:\n\n```bash\ncd ~/.clawdbot/skills/garmin-health-analysis\n# or: cd <workspace>/skills/garmin-health-analysis\ncp config.example.json config.json\n# Edit config.json and add your email and password\n```\n\n**config.json:**\n```json\n{\n  \"email\": \"your-email@example.com\",\n  \"password\": \"your-password\"\n}\n```\n\n**Note**: `config.json` is gitignored to keep your credentials secure.\n\n#### Option C: Command Line\n\nPass credentials directly when authenticating:\n```bash\npython3 scripts/garmin_auth.py login \\\n  --email YOUR_EMAIL@example.com \\\n  --password YOUR_PASSWORD\n```\n\n### 3. Authenticate\n\nLogin to Garmin Connect and save session tokens:\n\n```bash\npython3 scripts/garmin_auth.py login\n```\n\nThis uses credentials from (in priority order):\n1. Command line arguments (`--email`, `--password`)\n2. Local config file (`config.json`)\n3. Environment variables (`GARMIN_EMAIL`, `GARMIN_PASSWORD`)\n4. Clawdbot config (`skills.entries.garmin-health-analysis.env`)\n\nSession tokens are stored in `~/.clawdbot/garmin-tokens.json` and auto-refresh.\n\nCheck authentication status:\n```bash\npython3 scripts/garmin_auth.py status\n```\n\n## Fetching Data\n\nUse `scripts/garmin_data.py` to get JSON data:\n\n```bash\n# Sleep (last 7 days default)\npython3 scripts/garmin_data.py sleep --days 14\n\n# Body Battery (Garmin's recovery metric)\npython3 scripts/garmin_data.py body_battery --days 30\n\n# HRV data\npython3 scripts/garmin_data.py hrv --days 30\n\n# Heart rate (resting, max, min)\npython3 scripts/garmin_data.py heart_rate --days 7\n\n# Activities/workouts\npython3 scripts/garmin_data.py activities --days 30\n\n# Stress levels\npython3 scripts/garmin_data.py stress --days 7\n\n# Combined summary with averages\npython3 scripts/garmin_data.py summary --days 7\n\n# Custom date range\npython3 scripts/garmin_data.py sleep --start 2026-01-01 --end 2026-01-15\n\n# User profile\npython3 scripts/garmin_data.py profile\n```\n\nOutput is JSON to stdout. Parse it to answer user questions.\n\n## Generating Charts\n\nUse `scripts/garmin_chart.py` for interactive HTML visualizations:\n\n```bash\n# Sleep analysis (hours + scores)\npython3 scripts/garmin_chart.py sleep --days 30\n\n# Body Battery recovery chart (color-coded)\npython3 scripts/garmin_chart.py body_battery --days 30\n\n# HRV & resting heart rate trends\npython3 scripts/garmin_chart.py hrv --days 90\n\n# Activities summary (by type, calories)\npython3 scripts/garmin_chart.py activities --days 30\n\n# Full dashboard (all 4 charts)\npython3 scripts/garmin_chart.py dashboard --days 30\n\n# Save to specific file\npython3 scripts/garmin_chart.py dashboard --days 90 --output ~/Desktop/garmin-health.html\n```\n\nCharts open automatically in the default browser. They use Chart.js with a modern gradient design, stat cards, and interactive tooltips.\n\n## Answering Questions\n\n| User asks | Action |\n|-----------|--------|\n| \"How did I sleep last night?\" | `garmin_data.py summary --days 1`, report sleep hours + score |\n| \"How's my recovery this week?\" | `garmin_data.py body_battery --days 7`, report average + trend |\n| \"Show me my health for the last month\" | `garmin_chart.py dashboard --days 30` |\n| \"Is my HRV improving?\" | `garmin_data.py hrv --days 30`, analyze trend |\n| \"What workouts did I do this week?\" | `garmin_data.py activities --days 7`, list activities with details |\n| \"How's my resting heart rate?\" | `garmin_data.py heart_rate --days 7`, report average + trend |\n\n## Key Metrics\n\n### Body Battery (0-100)\nGarmin's proprietary recovery metric based on HRV, stress, sleep, and activity:\n- **High (75-100)**: Fully recharged, ready for high intensity\n- **Medium (50-74)**: Moderate energy, good for regular activity\n- **Low (25-49)**: Limited energy, recovery needed\n- **Very Low (0-24)**: Depleted, prioritize rest\n\n### Sleep Scores (0-100)\nOverall sleep quality based on duration, stages, and disturbances:\n- **Excellent (90-100)**: Optimal restorative sleep\n- **Good (80-89)**: Quality sleep with minor issues\n- **Fair (60-79)**: Adequate but could improve\n- **Poor (0-59)**: Significant sleep deficiencies\n\n### HRV (Heart Rate Variability)\nMeasured in milliseconds, higher is generally better:\n- Indicates nervous system balance and recovery capacity\n- Track **trends** over time (increasing = improving recovery)\n- Affected by sleep, stress, training load, illness\n- Normal range varies by individual (20-200+ ms)\n\n### Resting Heart Rate (bpm)\nLower generally indicates better cardiovascular fitness:\n- **Athletes**: 40-60 bpm\n- **Fit adults**: 60-70 bpm\n- **Average adults**: 70-80 bpm\n- Sudden increases may indicate stress, illness, or overtraining\n\n### Stress Levels\nBased on HRV analysis throughout the day:\n- **Low stress**: Rest and recovery periods\n- **Medium stress**: Normal daily activities\n- **High stress**: Physical activity or mental pressure\n\n## Health Analysis\n\nWhen users ask for insights or want to understand their trends, use `references/health_analysis.md` for:\n- Science-backed interpretation of all metrics\n- Normal ranges by age and fitness level\n- Pattern detection (weekly trends, recovery cycles, training load balance)\n- Actionable recommendations based on data\n- Warning signs that suggest rest or medical consultation\n\n### Analysis workflow\n1. Fetch data: `python3 scripts/garmin_data.py summary --days N`\n2. Read `references/health_analysis.md` for interpretation framework\n3. Apply the analysis framework: Status → Trends → Patterns → Insights → Recommendations\n4. Always include disclaimer that this is informational, not medical advice\n\n## Troubleshooting\n\n### Authentication Issues\n- **\"Invalid credentials\"**: Double-check email/password, try logging into Garmin Connect web\n- **\"Tokens expired\"**: Run login again: `python3 scripts/garmin_auth.py login ...`\n- **\"Too many requests\"**: Garmin rate-limits; wait a few minutes and try again\n\n### Missing Data\n- Some metrics require specific Garmin devices (Body Battery needs HRV-capable devices)\n- Historical data may have gaps if device wasn't worn\n- New accounts may have limited history\n\n### Library Issues\n- If `garminconnect` import fails: `pip3 install --upgrade garminconnect`\n- Garmin occasionally changes their API; update the library if requests fail\n\n## Privacy Note\n\n- Credentials are stored locally in `~/.clawdbot/garmin-tokens.json`\n- Session tokens refresh automatically\n- No data is sent anywhere except to Garmin's official servers\n- You can revoke access anytime by deleting the tokens file\n\n## Comparison: Garmin vs Whoop\n\n| Feature | Garmin | Whoop |\n|---------|--------|-------|\n| **Recovery metric** | Body Battery (0-100) | Recovery Score (0-100%) |\n| **HRV tracking** | Yes (nightly average) | Yes (detailed) |\n| **Sleep stages** | Light, Deep, REM, Awake | Light, SWS, REM, Awake |\n| **Activity tracking** | Built-in GPS, many sport modes | Strain score (0-21) |\n| **Stress** | All-day stress levels | Not directly tracked |\n| **API** | Unofficial (garminconnect) | Official OAuth |\n| **Device types** | Watches, fitness trackers | Wearable band only |\n\n## References\n\n- `references/api.md` — Garmin Connect API details (unofficial)\n- `references/health_analysis.md` — Science-backed health data interpretation\n- [garminconnect library](https://github.com/cyberjunky/python-garminconnect) — Python API wrapper\n- [Garmin Connect](https://connect.garmin.com) — Official web interface\n\n## Version Info\n\n- **Created**: 2026-01-25\n- **Author**: EversonL & Claude\n- **Version**: 1.2.0\n- **Dependencies**: garminconnect, fitparse, gpxpy (Python libraries)\n- **License**: MIT\n","topics":["Health"],"tags":{"latest":"1.2.2"},"stats":{"comments":0,"downloads":5390,"installsAllTime":203,"installsCurrent":17,"stars":12,"versions":11},"createdAt":1769382343704,"updatedAt":1778485852489},"latestVersion":{"version":"1.2.2","createdAt":1769387065409,"changelog":"Repository cleanup: Removed old MCP server files (CLAUDE_DESKTOP.md, mcp_server.py, requirements.txt). This repo is now focused exclusively on the Clawdbot skill for automated health monitoring. Claude Desktop users should use the dedicated MCP server at github.com/eversonl/garmin-health-mcp-server. Both can coexist with shared authentication.","license":null},"metadata":{"setup":[{"key":"GARMIN_EMAIL","required":true},{"key":"GARMIN_PASSWORD","required":true}],"os":null,"systems":null},"owner":{"handle":"eversonl","userId":"s17bm2cmyxsx3kz3n817vc3by5884ren","displayName":"eversonl","image":"https://avatars.githubusercontent.com/u/54025?v=4"},"moderation":null}