Skill: vraj1512/whoop-openclaw-skill (version 1.0.0)

--- name: whoop description: Fetch and analyze Whoop recovery, strain, sleep, and HRV data via the Whoop API. Use when the user asks about their Whoop metrics, recovery status, sleep quality, daily strain, HRV trends, workout data, or wants health/training insights based on Whoop data. Also use for daily morning briefings, weekly analysis, trend tracking, or real-time health alerts. --- # Whoop Integration Interact with the Whoop API to fetch and analyze recovery, strain, sleep, HRV, and workout data. ## Quick Start ### First-time Setup **Prerequisites:** - Python 3.7+ - `requests` library: `pip install requests` **Step 1: Create Whoop Developer App** 1. Go to https://app.whoop.com/ → Settings → Developer 2. Click "Create Application" 3. Fill in the required fields: - **Application Name**: Your choice (e.g., "Personal Whoop Assistant") - **Privacy Policy URL**: You need a public URL (see options below) - **Redirect URI**: You need a callback URL (see options below) - **Webhook URL**: Leave blank (optional for basic usage) 4. Save your **Client ID** and **Client Secret** (keep these private!) **Privacy Policy & Redirect URI Options:** *Option A - Quick GitHub Pages Setup:* 1. Create a GitHub repo (e.g., `whoop-oauth`) 2. Add the privacy/redirect HTML files from `references/oauth-pages/` 3. Enable GitHub Pages in repo settings 4. Use URLs like: - Privacy: `https://yourusername.github.io/whoop-oauth/privacy.html` - Redirect: `https://yourusername.github.io/whoop-oauth/redirect.html` *Option B - Use your own domain:* - Host the HTML files on your existing website *Option C - Local testing only:* - Privacy: `http://localhost/privacy.html` (Whoop may not accept this) - Redirect: `http://localhost:8080/callback` **Step 2: Complete OAuth Flow** 1. Create `whoop-config.json` with your app credentials: ```json { "client_id": "your-client-id-here", "client_secret": "your-client-secret-here", "redirect_uri": "https://yourusername.github.io/whoop-oauth/redirect.html" } ``` 2. Generate authorization URL and authorize: ```bash python3 scripts/whoop_oauth.py --config whoop-config.json ``` 3. Click the authorization URL, log in to Whoop, and authorize 4. Copy the authorization code from the redirect page 5. Exchange code for access token: ```bash python3 scripts/whoop_oauth.py --config whoop-config.json exchange <CODE> ``` 6. Token is automatically saved to `~/.whoop_token` **Step 3: Test Connection** ```bash python3 scripts/whoop_client.py --action profile ``` You should see your Whoop profile information! ### Common Commands **Today's summary** (recovery + sleep + strain): ```bash python3 scripts/whoop_client.py --action today ``` **Specific metrics:** ```bash # Recovery data (last 7 days) python3 scripts/whoop_client.py --action recovery --days 7 # Sleep data python3 scripts/whoop_client.py --action sleep --days 7 # Cycle data (strain, HRV, calories) python3 scripts/whoop_client.py --action cycle --days 7 # Workout history python3 scripts/whoop_client.py --action workout --days 10 ``` **Get raw JSON** (for parsing/analysis): ```bash python3 scripts/whoop_client.py --action today --json ``` ## Analysis Workflows ### Morning Briefing 1. Fetch today's data: ```bash python3 scripts/whoop_client.py --action today --json ``` 2. Analyze and provide insights: - **Recovery score**: Green (67-100%), Yellow (34-66%), Red (0-33%) - **HRV**: Compare to user's baseline (track trends, not absolute values) - **Sleep**: Check duration, quality, debt/credit - **Recommendations**: Based on recovery, suggest high/moderate/low strain day Example briefing: > "🔋 Recovery: 85% (Green) - Your body is well-recovered! > > 📊 HRV: 68ms (up 8% from baseline) > ❤️ RHR: 52 bpm (stable) > > 😴 Sleep: 8.2 hours, 92% performance > > 💪 Ready for a high-strain day. Go crush that workout!" ### Weekly Analysis 1. Fetch week of data: ```bash python3 scripts/whoop_client.py --action recovery --days 7 --json python3 scripts/whoop_client.py --action sleep --days 7 --json python3 scripts/whoop_client.py --action cycle --days 7 --json ``` 2. Identify trends: - HRV trend (increasing/decreasing) - Sleep consistency - Strain vs recovery balance - Patterns (e.g., low recovery after high strain days) 3. Provide recommendations: - Adjust training load - Improve sleep habits - Plan recovery days ### Real-time Alerts Monitor for warning signs: - **HRV drops >20% from baseline** → Consider rest day - **Recovery <33% for 2+ consecutive days** → Prioritize recovery - **Sleep performance <50% for 3+ days** → Focus on sleep - **High strain (>17) with low recovery (<40%)** → Risk of overtraining ## Data Interpretation Guide For detailed metric interpretation and optimal ranges, see `references/whoop-api.md`. **Key principles:** - **Track trends, not absolute values** - HRV/RHR baselines vary by individual - **Match strain to recovery** - High recovery = can handle high strain - **Consistency matters** - Regular sleep schedule improves recovery - **Listen to your body** - Metrics are guides, not rules ## Troubleshooting ### Setup Issues **"Privacy Policy URL must be HTTPS"**: - Whoop requires HTTPS URLs (not HTTP) - Use GitHub Pages, Netlify, or your own HTTPS domain - Local URLs (`localhost`) won't work for production apps **"Redirect URI mismatch"**: - The redirect URI must match EXACTLY what you configured in Whoop - Check for trailing slashes, http vs https, etc. - Example: `https://example.com/redirect.html` ≠ `https://example.com/redirect.html/` **OAuth code expired**: - Authorization codes expire quickly (usually within 10 minutes) - Generate a new auth URL and try again immediately ### API Issues **401 Unauthorized**: - Token expired → Re-run OAuth flow to get a new token - Invalid token → Check `~/.whoop_token` file exists and contains valid token - Wrong scopes → Make sure you authorized all required scopes **404 Not Found** (for sleep/cycle endpoints): - Some endpoints may not be available depending on API version - Check Whoop developer docs for current endpoint structure - Try fetching recovery data which includes sleep-related metrics **No data returned**: - Whoop needs to be synced recently (open Whoop app to sync) - Check date range (data only available for dates when you wore Whoop) - New users may have limited historical data **Rate limit errors**: - Default limits: 10,000/day, 100/minute - Spread out requests if hitting limits - Use pagination (`next_token`) for large data fetches ### Data Issues **Missing metrics**: - Some metrics require Whoop 4.0 (older devices have limited data) - Sleep data delayed ~1-2 hours after waking (processing time) - Recovery score requires previous night's sleep to be processed **Unexpected values**: - HRV and RHR vary by individual - track trends, not absolute values - Recovery score can be affected by alcohol, illness, stress - Strain accumulates throughout the day (starts low in morning) ### Getting Help 1. Check Whoop Developer Docs: https://developer.whoop.com/ 2. Review your app settings: https://app.whoop.com/settings/developer 3. Test with Whoop's API explorer (if available) 4. Verify your token with `--action profile` (simplest endpoint)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)