Garmin Health Analysis

Query health metrics from Garmin Connect and generate interactive HTML charts.

Two Installation Paths

This skill supports two different setups:

1. Clawdbot Skill (this guide) - Use with Clawdbot for automation and proactive health monitoring
2. MCP Server (see MCP setup guide) - Use with standard Claude Desktop as an MCP server

Choose the path that matches your use case. You can also use both simultaneously!

---

Clawdbot Skill Setup (first time only)

1. Install Dependencies

pip3 install garminconnect

2. Configure Credentials

You have three options to provide your Garmin Connect credentials:

Option A: Clawdbot Config (Recommended - UI configurable)

Add credentials to ~/.clawdbot/clawdbot.json:

{
  "skills": {
    "entries": {
      "garmin-health-analysis": {
        "enabled": true,
        "env": {
          "GARMIN_EMAIL": "your-email@example.com",
          "GARMIN_PASSWORD": "your-password"
        }
      }
    }
  }
}

Tip: You can also set these through the Clawdbot UI in the Skills settings panel.

Option B: Local Config File

Create a config file in the skill directory:

cd ~/.clawdbot/skills/garmin-health-analysis
# or: cd <workspace>/skills/garmin-health-analysis
cp config.example.json config.json
# Edit config.json and add your email and password

config.json:

{
  "email": "your-email@example.com",
  "password": "your-password"
}

Note: config.json is gitignored to keep your credentials secure.

Option C: Command Line

Pass credentials directly when authenticating:

python3 scripts/garmin_auth.py login \
  --email YOUR_EMAIL@example.com \
  --password YOUR_PASSWORD

3. Authenticate

Login to Garmin Connect and save session tokens:

python3 scripts/garmin_auth.py login

This uses credentials from (in priority order):

1. Command line arguments (--email, --password)
2. Local config file (config.json)
3. Environment variables (GARMIN_EMAIL, GARMIN_PASSWORD)
4. Clawdbot config (skills.entries.garmin-health-analysis.env)

Session tokens are stored in ~/.clawdbot/garmin/ (garth tokenstore) and auto-refresh on subsequent calls.

If you have existing tokens from a previous version (~/.garminconnect/), they are automatically migrated on first use.

Check authentication status:

python3 scripts/garmin_auth.py status

Fetching Data

Use scripts/garmin_data.py to get JSON data:

# Sleep (last 7 days default)
python3 scripts/garmin_data.py sleep --days 14

# Body Battery (Garmin's recovery metric)
python3 scripts/garmin_data.py body_battery --days 30

# HRV data
python3 scripts/garmin_data.py hrv --days 30

# Heart rate (resting, max, min)
python3 scripts/garmin_data.py heart_rate --days 7

# Activities/workouts (now includes activity_id)
python3 scripts/garmin_data.py activities --days 30

# Stress levels
python3 scripts/garmin_data.py stress --days 7

# Combined summary with averages
python3 scripts/garmin_data.py summary --days 7

# Custom date range
python3 scripts/garmin_data.py sleep --start 2026-01-01 --end 2026-01-15

# User profile
python3 scripts/garmin_data.py profile

Activity Splits (per-lap data)

Get lap-by-lap data for a specific activity — average/max HR, speed, distance, power, cadence per lap:

# Get lap splits for an activity (use activities to find activity_id)
python3 scripts/garmin_data.py activity_splits --activity-id 600107330

Returns per-lap: lap_index, distance_meters, duration_seconds, average_speed, max_speed, avg_hr, max_hr, calories, elevation_gain, average_power, normalized_power, average_run_cadence, intensity_type, etc.

Activity Detail (per-second time-series)

Get second-by-second data for a specific activity — heart rate, speed, distance, elevation, power, cadence, and more:

# All metrics, every second (full resolution)
python3 scripts/garmin_data.py activity_detail --activity-id 600107330

# Specific metrics only (faster, smaller output)
python3 scripts/garmin_data.py activity_detail --activity-id 600107330 \
  --metrics directHeartRate,directSpeed,sumDistance

# Sample every 30 seconds (good for quick overview of a long activity)
python3 scripts/garmin_data.py activity_detail --activity-id 600107330 \
  --sample-interval 30

# Common metrics:
#   directHeartRate   - Heart rate (bpm)
#   directSpeed       - Speed (m/s)
#   sumDistance        - Cumulative distance (m)
#   directElevation   - Elevation (m)
#   directPower       - Power (watts, running/cycling)
#   directRunCadence  - Cadence (spm for running)
#   directTimestamp   - Timestamp (ms epoch)
#   directLatitude    - Latitude
#   directLongitude   - Longitude
#   directGradeAdjustedSpeed - Grade-adjusted speed (m/s)
#   directVerticalOscillation - Vertical oscillation (cm)
#   directGroundContactTime  - Ground contact time (ms)
#   directStrideLength - Stride length (cm)
#   directVerticalRatio - Vertical ratio (%)
#   directPerformanceCondition - Performance condition

Output is JSON to stdout. Parse it to answer user questions.

Generating Charts

Use scripts/garmin_chart.py for interactive HTML visualizations:

# Sleep analysis (hours + scores)
python3 scripts/garmin_chart.py sleep --days 30

# Body Battery recovery chart (color-coded)
python3 scripts/garmin_chart.py body_battery --days 30

# HRV & resting heart rate trends
python3 scripts/garmin_chart.py hrv --days 90

# Activities summary (by type, calories)
python3 scripts/garmin_chart.py activities --days 30

# Full dashboard (all 4 charts)
python3 scripts/garmin_chart.py dashboard --days 30

# Save to specific file
python3 scripts/garmin_chart.py dashboard --days 90 --output ~/Desktop/garmin-health.html

Charts open automatically in the default browser. They use Chart.js with a modern gradient design, stat cards, and interactive tooltips.

Answering Questions

User asks	Action
"How did I sleep last night?"	garmin_data.py summary --days 1, report sleep hours + score
"How's my recovery this week?"	garmin_data.py body_battery --days 7, report average + trend
"Show me my health for the last month"	garmin_chart.py dashboard --days 30
"Is my HRV improving?"	garmin_data.py hrv --days 30, analyze trend
"What workouts did I do this week?"	garmin_data.py activities --days 7, list activities with details
"How's my resting heart rate?"	garmin_data.py heart_rate --days 7, report average + trend
"Show me my heart rate during my run"	garmin_data.py activity_detail --activity-id ID --metrics directHeartRate,directSpeed --sample-interval 30
"What were my lap splits?"	garmin_data.py activity_splits --activity-id ID, report per-lap HR + pace
"How did my pace change over the run?"	garmin_data.py activity_detail --activity-id ID --metrics directSpeed,sumDistance --sample-interval 60

Key Metrics

Body Battery (0-100)

Garmin's proprietary recovery metric based on HRV, stress, sleep, and activity:

• High (75-100): Fully recharged, ready for high intensity
• Medium (50-74): Moderate energy, good for regular activity
• Low (25-49): Limited energy, recovery needed
• Very Low (0-24): Depleted, prioritize rest

Sleep Scores (0-100)

Overall sleep quality based on duration, stages, and disturbances:

• Excellent (90-100): Optimal restorative sleep
• Good (80-89): Quality sleep with minor issues
• Fair (60-79): Adequate but could improve
• Poor (0-59): Significant sleep deficiencies

HRV (Heart Rate Variability)

Measured in milliseconds, higher is generally better:

• Indicates nervous system balance and recovery capacity
• Track trends over time (increasing = improving recovery)
• Affected by sleep, stress, training load, illness
• Normal range varies by individual (20-200+ ms)

Resting Heart Rate (bpm)

Lower generally indicates better cardiovascular fitness:

• Athletes: 40-60 bpm
• Fit adults: 60-70 bpm
• Average adults: 70-80 bpm
• Sudden increases may indicate stress, illness, or overtraining

Stress Levels

Based on HRV analysis throughout the day:

• Low stress: Rest and recovery periods
• Medium stress: Normal daily activities
• High stress: Physical activity or mental pressure

Health Analysis

When users ask for insights or want to understand their trends, use references/health_analysis.md for:

• Science-backed interpretation of all metrics
• Normal ranges by age and fitness level
• Pattern detection (weekly trends, recovery cycles, training load balance)
• Actionable recommendations based on data
• Warning signs that suggest rest or medical consultation

Analysis workflow

1. Fetch data: python3 scripts/garmin_data.py summary --days N
2. Read references/health_analysis.md for interpretation framework
3. Apply the analysis framework: Status → Trends → Patterns → Insights → Recommendations
4. Always include disclaimer that this is informational, not medical advice

Troubleshooting

Authentication Issues

• "Invalid credentials": Double-check email/password, try logging into Garmin Connect web
• "Tokens expired": Run login again: python3 scripts/garmin_auth.py login ...
• "Too many requests": Garmin rate-limits; wait a few minutes and try again

Missing Data

• Some metrics require specific Garmin devices (Body Battery needs HRV-capable devices)
• Historical data may have gaps if device wasn't worn
• New accounts may have limited history

Library Issues

• If garminconnect import fails: pip3 install --upgrade garminconnect
• Garmin occasionally changes their API; update the library if requests fail

Privacy Note

• Credentials are stored locally in ~/.clawdbot/garmin/ (garth tokenstore directory)
• Session tokens auto-refresh; if they expire, the module falls back to credentials from config/env
• Legacy tokens from ~/.garminconnect/ are automatically migrated on first use
• Rate-limited? The auth module retries once after 30s and tells you what to do
• No data is sent anywhere except to Garmin's official servers
• You can revoke access anytime by deleting the ~/.clawdbot/garmin/ directory

Comparison: Garmin vs Whoop

Feature	Garmin	Whoop
Recovery metric	Body Battery (0-100)	Recovery Score (0-100%)
HRV tracking	Yes (nightly average)	Yes (detailed)
Sleep stages	Light, Deep, REM, Awake	Light, SWS, REM, Awake
Activity tracking	Built-in GPS, many sport modes	Strain score (0-21)
Stress	All-day stress levels	Not directly tracked
API	Unofficial (garminconnect)	Official OAuth
Device types	Watches, fitness trackers	Wearable band only

References

• references/api.md — Garmin Connect API details (unofficial)
• references/health_analysis.md — Science-backed health data interpretation
• garminconnect library — Python API wrapper
• Garmin Connect — Official web interface

Version Info

• Created: 2026-01-25
• Author: EversonL & Claude
• Version: 1.3.0
• Dependencies: garminconnect, curl_cffi, fitparse, gpxpy (Python libraries)
• License: MIT