WHOOP Tracker

Access WHOOP fitness tracker data via API, including recovery scores, sleep metrics, workout stats, daily strain, and body measurements. Use when the user asks about their WHOOP data, fitness metrics, recovery status, sleep quality, workout performance, or wants to track health trends.

Security Scan

The skill appears to do what it says — it implements a WHOOP API client and CLI scripts that read/write OAuth credentials and tokens under ~/.whoop — but the code and docs contain multiple implementation bugs, mismatches, and rough edges that you should review before use.

Purpose & Capability

Name and description align with included code: a Python WHOOP API client and scripts for profile, recovery, sleep, and workouts. The skill uses OAuth and stores credentials/tokens under ~/.whoop which is appropriate for this purpose. Minor inconsistencies exist between SKILL.md, references, and whoop_client.py (base URL path includes '/developer', some endpoint paths/versions differ between docs and code, and get_body_measurements endpoint path differs from the reference), but these are implementation bugs rather than evidence of misrepresentation.

Instruction Scope

SKILL.md instructs the agent/user to create ~/.whoop/credentials.json, run an OAuth flow, and execute the provided scripts — all scoped to WHOOP data. The runtime instructions and scripts read/write only the described credentials and token files and call the WHOOP API. However the SKILL.md and code have mismatches (endpoints, path conventions) and the included AUDIT.md flags missing error handling and other faults; follow-up fixes are needed to avoid runtime failures.

Install Mechanism

No remote downloads or third-party install artifacts beyond a local install.sh that runs 'pip3 install requests'. All code is packaged with the skill; install method is low risk compared with arbitrary remote downloads.

Credentials

No environment variables or unrelated cloud credentials are requested. The skill requires a WHOOP OAuth client_id/client_secret which the instructions place in ~/.whoop/credentials.json — this is proportional to the declared functionality. It does persist OAuth tokens to ~/.whoop/token.json (normal for an OAuth client).

Persistence & Privilege

The skill persists its own credentials/tokens under ~/.whoop and does not request always:true or system-wide configuration changes. It does not modify other skills or system-wide agents. Storing tokens locally is expected for this kind of client, but you should protect the credentials file (SKILL.md suggests chmod 600 which is appropriate).

Scan Findings in Context

[AUDIT_MD_PRESENT] expected: An included AUDIT.md documents multiple bugs (import path issues, missing dependency handling, OAuth flow fixes). Having an audit file is expected; its contents are useful signals that the code needs fixes before production use.

[USES_REQUESTS_LIBRARY] expected: The code imports and depends on the 'requests' library and the install script installs it. This is expected for a Python HTTP client.

[PERSIST_TOKENS_TO_HOME] expected: The client saves access/refresh tokens to ~/.whoop/token.json and sets restrictive permissions (chmod 600). Storing tokens locally is expected for an OAuth client, but users should be aware of the file location and secure it.

[HARDCODED_API_BASE_URL] expected: WHOOP_BASE_URL is hard-coded to 'https://api.prod.whoop.com/developer'. The SKILL.md lists 'https://api.prod.whoop.com' as the base — these mismatches are implementation inconsistencies rather than malicious obfuscation.

[AUDIT_CRITICAL_BUGS_LISTED] unexpected: AUDIT.md lists '12 critical bugs' that would break first-run usage (import path issues, missing dependency-handling). These are not expected as part of a polished skill and indicate the package may not work correctly without author fixes.

Assessment

This skill is coherent with its stated purpose (fetching WHOOP data) and does not request unrelated credentials, but it is not production-ready. Before installing or running: (1) review the code locally — it will create ~/.whoop/credentials.json and ~/.whoop/token.json and store your client_id/client_secret and tokens there; protect those files (chmod 600 is recommended); (2) be prepared to run 'pip3 install requests' or use the provided install.sh in a virtualenv; (3) expect runtime errors due to documented bugs in AUDIT.md (fix import paths or run scripts from the skill root, ensure endpoints and redirect_uri match your WHOOP app settings); (4) if you don't trust the source, run the scripts in an isolated VM/container or review/fix the code before using them with your live WHOOP account. If you want, I can list the specific code mismatches and exact fixes referenced in AUDIT.md to help get it working safely.

WHOOP API

Retrieve and analyze fitness data from WHOOP wearables via the official REST API.

Usage Snippet

# Install (if using Clawdhub)
clawdhub install whoop-tracker

# From the skill root:
python3 scripts/get_recovery.py --today
python3 scripts/get_sleep.py --last
python3 scripts/get_workouts.py --days 7
python3 scripts/get_profile.py

Prerequisites

• Python 3.7+
• requests library: pip3 install requests
  (or run bash scripts/install.sh)

Quick Start

1. Register Application

• Go to https://developer.whoop.com
• Create a new app and note your client_id and client_secret
• Set redirect URI (e.g., http://localhost:8080/callback)

2. Save Credentials

mkdir -p ~/.whoop
cat > ~/.whoop/credentials.json <<EOF
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
EOF
chmod 600 ~/.whoop/credentials.json

3. Authorize (see references/oauth.md for full guide)

• Open the authorization URL in browser
• User grants permissions → redirected with code
• Exchange code for tokens via WhoopClient.authenticate(code, redirect_uri)

4. Fetch Data

All scripts are run from the skill root directory:

# Today's recovery
python3 scripts/get_recovery.py --today

# Last night's sleep
python3 scripts/get_sleep.py --last

# Recent workouts
python3 scripts/get_workouts.py --days 7

# User profile
python3 scripts/get_profile.py

Core Data Types

Recovery

• Recovery Score (0-100): Readiness for strain
• HRV (RMSSD): Heart rate variability in milliseconds
• Resting Heart Rate: Morning baseline HR
• SPO2: Blood oxygen percentage
• Skin Temperature: Deviation from baseline in °C

Sleep

• Performance %: How well you slept vs. your sleep need
• Duration: Total time in bed and per stage (REM, SWS, light, awake)
• Efficiency %: Time asleep / time in bed
• Consistency %: How consistent your sleep schedule is
• Respiratory Rate: Breaths per minute
• Sleep Needed/Debt: Baseline need and accumulated debt

Cycle (Daily Strain)

• Strain Score: Cardiovascular load (0-21 scale)
• Kilojoules: Energy expenditure
• Average/Max Heart Rate: Daily HR metrics

Workout

• Strain: Activity-specific strain score
• Sport: Activity type (running, cycling, etc.)
• Heart Rate Zones: Time spent in each of 6 zones
• Distance/Altitude: GPS metrics (if available)

API Endpoints

Base URL: https://api.prod.whoop.com

See references/api-reference.md for full endpoint documentation with response schemas.

User Profile:

• GET /v1/user/profile/basic — Name, email
• GET /v1/user/body_measurement — Height, weight, max HR

Recovery:

• GET /v1/recovery — All recovery data (paginated)
• GET /v1/cycle/{cycleId}/recovery — Recovery for specific cycle

Sleep:

• GET /v1/sleep — All sleep records (paginated)
• GET /v1/sleep/{sleepId} — Specific sleep by ID
• GET /v1/cycle/{cycleId}/sleep — Sleep for specific cycle

Cycle:

• GET /v1/cycle — All physiological cycles (paginated)
• GET /v1/cycle/{cycleId} — Specific cycle by ID

Workout:

• GET /v1/workout — All workouts (paginated)
• GET /v1/workout/{workoutId} — Specific workout by ID

All collection endpoints support start, end (ISO 8601), limit (max 25), and nextToken (pagination cursor).

Required OAuth Scopes

• read:profile — User name and email
• read:body_measurement — Height, weight, max HR
• read:recovery — Recovery scores and HRV
• read:sleep — Sleep metrics and stages
• read:cycles — Daily strain data
• read:workout — Activity and workout data

Scripts

scripts/whoop_client.py

Core API client. Features:

• OAuth token storage and auto-refresh
• Token expiry tracking (proactive refresh)
• Rate limit handling (429 with retry)
• Automatic pagination iterators (iter_recovery, iter_sleep, iter_cycles, iter_workouts)

scripts/get_recovery.py

python3 scripts/get_recovery.py --today              # Today's recovery
python3 scripts/get_recovery.py --days 7             # Past week
python3 scripts/get_recovery.py --start 2026-01-20   # From date
python3 scripts/get_recovery.py --json               # Raw JSON output

scripts/get_sleep.py

python3 scripts/get_sleep.py --last       # Last night
python3 scripts/get_sleep.py --days 7     # Past week
python3 scripts/get_sleep.py --json       # Raw JSON output

scripts/get_workouts.py

python3 scripts/get_workouts.py --days 7             # Past week
python3 scripts/get_workouts.py --sport running       # Filter by sport
python3 scripts/get_workouts.py --json                # Raw JSON output

scripts/get_profile.py

python3 scripts/get_profile.py            # Profile + body measurements
python3 scripts/get_profile.py --json     # Raw JSON output

scripts/install.sh

bash scripts/install.sh                   # Install pip dependencies + setup guide

Troubleshooting

"ModuleNotFoundError: No module named 'requests'"

Install dependencies: pip3 install requests or bash scripts/install.sh

"Credentials not found at ~/.whoop/credentials.json"

Create the file with your OAuth client_id and client_secret (see Quick Start step 2).

"Not authenticated"

Complete the OAuth authorization flow (see references/oauth.md).

"401 Unauthorized" after token refresh fails

Your refresh token has expired. Re-authorize from the authorization URL.

"429 Too Many Requests"

Rate limit hit. The client automatically retries after the Retry-After period.

Empty results

Check your date range — use --days 7 or wider range. Ensure your OAuth scopes include the data type you're requesting.

References

• references/oauth.md — OAuth setup, token management, authorization flow
• references/api-reference.md — Complete API endpoint documentation with response schemas