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: 6. Click **Create** — you'll get a **Client ID** and **Client Secret** ### 2. Authenticate Run the OAuth login flow with your credentials: __CODE_BLOCK_0__ 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: __CODE_BLOCK_1__ Output is JSON to stdout. Parse it to answer user questions. ## Generating Charts Use scripts/whoop_chart.py for interactive HTML visualizations: __CODE_BLOCK_2__ 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