whoop-health

# Whoop Query health metrics from the Whoop API and generate interactive HTML charts. ## Setup (first time only) ### 1. Create a Whoop Developer App 1. Go to [developer-dashboard.whoop.com](https://developer-dashboard.whoop.com) 2. Sign in with your Whoop account credentials 3. Create a Team if prompted (any name works) 4. Click **Create App** (or go to [apps/create](https://developer-dashboard.whoop.com/apps/create)) 5. Fill in: - **App name**: anything (e.g., "Clawdbot") - **Scopes**: select ALL: `read:recovery`, `read:cycles`, `read:workout`, `read:sleep`, `read:profile`, `read:body_measurement` - **Redirect URI**: `http://localhost:9876/callback` 6. Click **Create** — you'll get a **Client ID** and **Client Secret** ### 2. Authenticate Run the OAuth login flow with your credentials: ```bash python3 scripts/whoop_auth.py login \ --client-id YOUR_CLIENT_ID \ --client-secret YOUR_CLIENT_SECRET ``` This opens a browser for Whoop authorization. Log in and approve access. Tokens are stored in `~/.clawdbot/whoop-tokens.json` and auto-refresh. Check status: `python3 scripts/whoop_auth.py status` ## Fetching Data Use `scripts/whoop_data.py` to get JSON data: ```bash # Sleep (last 7 days default) python3 scripts/whoop_data.py sleep --days 14 # Recovery scores python3 scripts/whoop_data.py recovery --days 30 # Strain/cycles python3 scripts/whoop_data.py cycles --days 7 # Workouts python3 scripts/whoop_data.py workouts --days 30 # Combined summary with averages python3 scripts/whoop_data.py summary --days 7 # Custom date range python3 scripts/whoop_data.py sleep --start 2026-01-01 --end 2026-01-15 # User profile / body measurements python3 scripts/whoop_data.py profile python3 scripts/whoop_data.py body ``` Output is JSON to stdout. Parse it to answer user questions. ## Generating Charts Use `scripts/whoop_chart.py` for interactive HTML visualizations: ```bash # Sleep analysis (performance + stages) python3 scripts/whoop_chart.py sleep --days 30 # Recovery bars (color-coded green/yellow/red) python3 scripts/whoop_chart.py recovery --days 30 # Strain & calories trend python3 scripts/whoop_chart.py strain --days 90 # HRV & resting heart rate trend python3 scripts/whoop_chart.py hrv --days 90 # Full dashboard (all 4 charts) python3 scripts/whoop_chart.py dashboard --days 30 # Save to specific file python3 scripts/whoop_chart.py dashboard --days 90 --output ~/Desktop/whoop.html ``` Charts open automatically in the default browser. They use Chart.js with dark theme, stat cards, and tooltips. ## Answering Questions | User asks | Action | |-----------|--------| | "How did I sleep?" | `whoop_data.py summary --days 7`, report sleep performance + hours | | "How's my recovery?" | `whoop_data.py recovery --days 7`, report scores + trend | | "Show me a chart for the last month" | `whoop_chart.py dashboard --days 30` | | "Is my HRV improving?" | `whoop_data.py recovery --days 30`, analyze trend | | "How much did I train this week?" | `whoop_data.py workouts --days 7`, list activities | ## Key Metrics - **Recovery** (0-100%): Green ≥67%, Yellow 34-66%, Red <34% - **Strain** (0-21): Daily exertion score based on HR - **Sleep Performance**: Actual sleep vs. sleep needed - **HRV** (ms): Higher = better recovery, track trend over time - **RHR** (bpm): Lower = better cardiovascular fitness ## Health Analysis When the user asks about their health, trends, or wants insights, use `references/health_analysis.md` for: - Science-backed interpretation of HRV, RHR, sleep stages, recovery, strain, SpO2 - Normal ranges by age and fitness level - Pattern detection (day-of-week effects, sleep debt, overtraining signals) - Actionable recommendations based on data - Red flags that suggest medical consultation ### Analysis workflow 1. Fetch data: `python3 scripts/whoop_data.py summary --days N` 2. Read `references/health_analysis.md` for interpretation framework 3. Apply the 5-step analysis: Status → Trends → Patterns → Insights → Flags 4. Always include disclaimer that this is not medical advice ## References - `references/api.md` — endpoint details, response schemas, pagination - `references/health_analysis.md` — science-backed health data interpretation guide