WHOOP Health Skill

Integrates with the WHOOP Developer API v2 to retrieve and analyze health/fitness data from a WHOOP band.

Setup

1. Create a Developer App

1. Go to developer.whoop.com and sign in with your WHOOP account
2. Create a new application; set Redirect URI to http://localhost:8080/callback
3. Save Client ID and Client Secret

2. Authenticate

Run the OAuth helper script to get an access token:

python3 scripts/whoop_auth.py --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

This opens a browser for authorization and saves tokens to ~/.whoop_tokens.json.

3. Fetch Data

# Fetch all data types (last 7 days)
python3 scripts/whoop_fetch.py --days 7

# Fetch specific data types
python3 scripts/whoop_fetch.py --days 30 --types recovery,sleep,workout,cycle

# Output as JSON
python3 scripts/whoop_fetch.py --days 7 --format json --output whoop_data.json

# Output as CSV (one file per data type)
python3 scripts/whoop_fetch.py --days 7 --format csv --output ./whoop_export/

Available Data Types

Analysis Workflows

Trend Analysis

python3 scripts/whoop_fetch.py --days 30 --types recovery,sleep --format json --output data.json

Then ask: "Analyze my HRV trend and sleep performance over the last 30 days. Identify patterns."

Recovery vs. Strain Correlation

Fetch recovery + cycle for 30+ days, then ask for correlation analysis between day Strain and next-day Recovery score.

Sleep Stage Breakdown

Fetch sleep data, request a breakdown of avg time in each stage (REM, SWS, Light, Awake) and flag nights below recommended thresholds.

Token Management

Tokens are stored at ~/.whoop_tokens.json. The fetch script auto-refreshes using the refresh token when the access token expires (24h lifetime).

To revoke access: python3 scripts/whoop_auth.py --revoke

API Reference

See references/api_endpoints.md for full endpoint list, parameters, and response schemas.

Environment Variables (alternative to flags)

export WHOOP_CLIENT_ID=your_client_id
export WHOOP_CLIENT_SECRET=your_client_secret