whoop-tracker_skill

Overview

This skill provides programmatic access to WHOOP fitness tracker data via the WHOOP REST API. It fetches recovery scores, sleep metrics, workout stats, daily strain (cycles), and body measurements and includes scripts and a client that handle OAuth, pagination, and retries.

How this skill works

The skill includes a Python client that authenticates with WHOOP using OAuth, stores and refreshes tokens, and exposes iterator helpers for paginated endpoints. Ready-to-use scripts call the client to retrieve recovery, sleep, workout, cycle, and profile data, and support date ranges, filtering, and raw JSON output. Rate limits, token expiry, and retries are handled automatically by the client.

When to use it

• When you want to pull your WHOOP recovery, HRV, or resting heart rate programmatically.
• When you need nightly sleep metrics, stage breakdown, efficiency, or respiratory rate for trend analysis.
• When you want recent workout details including strain, heart rate zones, distance, or sport type.
• When building dashboards or backups of WHOOP data for personal analytics or archiving.
• When automating reports that combine daily strain (cycle) and energy expenditure with recovery status.

Best practices

• Register an app at developer.whoop.com and save client_id/client_secret to ~/.whoop/credentials.json with restrictive permissions.
• Request only required OAuth scopes (read:recovery, read:sleep, read:workout, etc.) to minimize permission surface.
• Use provided iterator helpers (iter_sleep, iter_recovery, iter_workouts) to handle pagination safely.
• Run scripts with sensible date ranges (e.g., --days 7) to avoid large paginated requests and possible rate limits.
• Keep the requests dependency updated and re-authorize if you see 401 after refresh attempts.

Example use cases

• Generate a weekly recovery and sleep report for coaching or self-monitoring.
• Sync WHOOP workouts and strain into a personal training log or performance dashboard.
• Export nightly sleep stage data for long-term trend analysis or research.
• Build an alert when recovery drops below a threshold before a planned high-strain session.
• Archive body measurements and profile changes over time for longitudinal records.