whoop-connect

# whoop-connect

Connect your WHOOP band to OpenClaw so your agent can fetch your recovery, sleep, HRV, strain, and workout data.

Setup (once)

WHOOP does not have a public API. To access your own data, you need to register a personal developer app (free, takes 5 minutes). This gives you OAuth credentials so the skill can read your data on your behalf. All data stays local in `~/.whoop/whoop.db` — nothing is uploaded anywhere.

- Register at https://developer.whoop.com (sign in with your WHOOP account, create an app, get Client ID and Client Secret). Full walkthrough: `{baseDir}/references/setup-guide.md`
- Set env vars: `WHOOP_CLIENT_ID`, `WHOOP_CLIENT_SECRET`
- First invocation auto-creates config and runs OAuth

**When env vars are missing**, explain to the user: "WHOOP requires a free developer account to access your data via API. It takes about 5 minutes — I can walk you through it step by step." Then follow `{baseDir}/references/setup-guide.md`.

If config missing: `python3 {baseDir}/scripts/setup.py --init`, then ask user's language and `python3 {baseDir}/scripts/setup.py --set language=zh` (or `en`).
If token missing: `python3 {baseDir}/scripts/whoop_client.py auth`.
If deps missing: `bash {baseDir}/scripts/install.sh`.

Common commands

- Today's recovery: `python3 {baseDir}/scripts/whoop_client.py recovery --days 1`
- Last night's sleep: `python3 {baseDir}/scripts/whoop_client.py sleep --days 1`
- Recent workouts: `python3 {baseDir}/scripts/whoop_client.py workout --days 7`
- Weekly strain: `python3 {baseDir}/scripts/whoop_client.py cycle --days 7`
- Multi-day summary: `python3 {baseDir}/scripts/whoop_client.py trends --days 7`
- Single metric history: `python3 {baseDir}/scripts/db.py trends --metric <name> --days N`
- Profile: `python3 {baseDir}/scripts/whoop_client.py profile`
- Body measurements: `python3 {baseDir}/scripts/whoop_client.py body`
- Force sync: `python3 {baseDir}/scripts/daily_sync.py --days 2`
- Start auto-sync daemon: `python3 {baseDir}/scripts/auto_sync.py`
- Single sync check: `python3 {baseDir}/scripts/auto_sync.py --once`
- Auto-sync with custom interval: `python3 {baseDir}/scripts/auto_sync.py --interval 10`

Use `--json` for raw data when combining multiple queries. Use `--days N` to match user's time range ("this week" = 7, "this month" = 30).

Available metrics: `recovery_score`, `hrv`, `resting_hr`, `spo2`, `skin_temp`, `strain`, `sleep_duration`, `sleep_efficiency`, `sleep_performance`, `respiratory_rate`

Settings

- Change setting: `python3 {baseDir}/scripts/setup.py --set <key>=<value>`
- Show config: `python3 {baseDir}/scripts/setup.py --show`
- Re-run wizard: `python3 {baseDir}/scripts/setup.py`

Keys: `language` (en/zh), `detail_level` (compact/detailed), `units` (metric/imperial), `push_recovery`, `push_sleep`, `push_workout`, `webhook_enabled` (bool), `webhook_port` (int), `sync_interval` (int, minutes — polling interval when webhook is off, default 5), `sync_interval_webhook` (int, minutes — fallback interval when webhook is on, default 20), `daily_api_limit` (int, default 10000)

Users may change settings in natural language (e.g. "switch to Chinese", "use detailed mode"). Map to `--set` accordingly.

Auto-sync

The skill supports automatic data syncing with adaptive intervals:

- **No webhook**: polls WHOOP API every `sync_interval` minutes (default 5) as the primary data source
- **Webhook enabled**: webhook delivers real-time events; auto-sync polls every `sync_interval_webhook` minutes (default 20) as fallback
- **Dedup**: only new, scored records trigger notifications; already-seen data is silently skipped
- **API guard**: tracks daily API calls and pauses when `daily_api_limit` (default 10,000) is reached
- Start daemon: `python3 {baseDir}/scripts/auto_sync.py`
- Single check: `python3 {baseDir}/scripts/auto_sync.py --once`

Webhook (optional)

For real-time push, set up webhooks — see `{baseDir}/references/setup-guide.md` § "Optional: Webhook Setup". Set `webhook_enabled=true` in config. The webhook server writes a heartbeat file so auto-sync can detect if webhook is healthy and reduce polling frequency automatically.

Notes

- Never fabricate health data. If a command returns empty or errors, say so.
- Never expose WHOOP_CLIENT_ID, WHOOP_CLIENT_SECRET, or token contents in output.
- Never delete DB files or config without explicit user confirmation.
- Confirm before changing user settings.
- Respect `language` and `detail_level` from config.
- If WHOOP API returns 429, the client auto-retries. Do not flood.

Troubleshooting

- `ModuleNotFoundError`: `bash {baseDir}/scripts/install.sh`
- `WHOOP_CLIENT_ID must be set`: check env vars
- `No refresh token`: `python3 {baseDir}/scripts/whoop_client.py auth`
- `401 Unauthorized`: re-authorize with `auth`
- `500 Server Error`: transient WHOOP-side issue, retry in a few minutes
- Empty results: widen `--days`; data may not be scored yet

References

- `{baseDir}/references/setup-guide.md` — New user onboarding + webhook setup
- `{baseDir}/references/api-reference.md` — WHOOP API v2 field documentation
- `{baseDir}/references/webhook-events.md` — Webhook event types and payload format
- WHOOP Developer Docs: https://developer.whoop.com/docs/developing/user-data/recovery
- WHOOP API Reference: https://developer.whoop.com/api