Whoop
Query health metrics from the Whoop API and generate interactive HTML charts.
Setup (first time only)
1. Create a Whoop Developer App
- Go to developer-dashboard.whoop.com
- Sign in with your Whoop account credentials
- Create a Team if prompted (any name works)
- Click Create App (or go to apps/create)
- 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
- Click Create — you'll get a Client ID and Client Secret
2. Authenticate
Run the OAuth login flow with your credentials:
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:
# 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:
# 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
- Fetch data:
python3 scripts/whoop_data.py summary --days N
- Read
references/health_analysis.md
for interpretation framework
- Apply the 5-step analysis: Status → Trends → Patterns → Insights → Flags
- Always include disclaimer that this is not medical advice
References
references/api.md
— endpoint details, response schemas, paginationreferences/health_analysis.md
— science-backed health data interpretation guide
