WHOOP Lab

intent

Fetch, interpret, chart, and track WHOOP health metrics (recovery, HRV, resting HR, sleep, strain, workouts) via the WHOOP Developer API v2. Use this skill when querying any WHOOP metric, generating visual dashboards, planning or monitoring health experiments with auto-captured baselines and post-workout segmentation, logging stats to Obsidian, correlating health data with life context, or flagging suppressed recovery trends. The skill handles OAuth token refresh, full history pagination, and science-backed metric interpretation (HRV ranges by age, overtraining signals, sleep stage targets, medication context).

inputs

External connections:

• WHOOP Developer API v2 (https://api.prod.whoop.com/developer/v2)
  • Requires: free WHOOP Developer App (OAuth 2.0, client ID + secret)
  • Scopes: all read:* + offline
  • Rate limit: check WHOOP docs; implement exponential backoff on 429 responses
  • Token lifetime: access tokens expire; refresh flow required

System requirements:

• Python 3.7+
• Dependencies: pip install -r requirements.txt
• Optional: git (only if pushing Obsidian vault; skip if vault not configured)
• Optional: Obsidian vault for daily note logging

Configuration files (created in ~/.config/whoop-skill/):

• credentials.json , OAuth tokens (access_token, refresh_token, expires_at). Created by auth.py on first setup.
• experiments.json , experiment tracking data (created on first plan command).
• config.json (optional) , copy from config.example.json to override:
  • creds_path: path to credentials file (default: ~/.config/whoop-skill/credentials.json)
  • vault_path: Obsidian vault directory (e.g. ~/my-obsidian-vault)
  • daily_notes_subdir: subdirectory within vault for daily notes (default: Daily Notes)
  • timezone: IANA timezone (default: America/New_York)
  • logged_by: name for log attribution (default: Assistant)

Environment variables (optional):

• WHOOP_CREDS_PATH: override credentials file location
• WHOOP_VAULT_PATH: override Obsidian vault path

procedure

setup (one-time)

step 1: install python dependencies

• Input: repository with requirements.txt
• Run: pip install -r requirements.txt
• Output: dependencies installed locally

step 2: decide oauth callback method

• Choose local server (http://localhost:8888/callback, auto-catches redirect on same machine) OR manual code paste (print URL, user authorizes in any browser, pastes code back)
• Output: decision recorded for step 4

step 3: create whoop developer app

• Input: WHOOP account access, https://developer-dashboard.whoop.com
• Create team (any name)
• Click Create App:
  • App name: any name (e.g. "My WHOOP Skill")
  • Redirect URI: http://localhost:8888/callback (same for both callback methods)
  • Scopes: select all read:* scopes + offline
• Copy Client ID and Client Secret
• Output: Client ID, Client Secret (needed next)

step 4: run auth script

• Input: Client ID, Client Secret, callback method choice from step 2
• Run: python3 scripts/auth.py
  • Script prompts for Client ID, Client Secret
  • Script asks which callback method (local server or manual)
  • Script opens authorization URL (local server) or prints it (manual)
  • If local server: automatic redirect capture on localhost:8888
  • If manual: user opens URL in browser, copies code, pastes into script
  • Script exchanges code for access token + refresh token
• Output: ~/.config/whoop-skill/credentials.json with tokens + expires_at timestamp

step 5 (optional): configure paths

• Input: existing ~/.config/whoop-skill/ directory from step 4
• Copy config.example.json from skill root to ~/.config/whoop-skill/config.json
• Edit config.json to override vault_path, timezone, etc.
• Output: config.json in place; remaining scripts will read it

fetching data

step 1: check token expiry

• Input: ~/.config/whoop-skill/credentials.json
• Read expires_at timestamp
• If expires_at <= now + 60 seconds: run python3 scripts/refresh_token.py
  • Input: current credentials file
  • Script calls /auth/token endpoint with refresh_token
  • Output: credentials file updated with new access_token + new expires_at
• Output: valid access token ready for API calls

step 2: call fetch.py with endpoint + filters

• Input: endpoint (e.g. /recovery, /activity/sleep, /activity/workout, /user/profile/basic), optional --limit, --start, --end
• Run: python3 scripts/fetch.py <endpoint> [--limit N] [--start YYYY-MM-DD] [--end YYYY-MM-DD]
• Script uses access token from credentials file, calls API, handles pagination if limit > 100
• Output: JSON array to stdout (e.g. [{id, ..., score: {recovery_score, hrv_rmssd_milli, ...}}, ...])

step 3: parse + present

• Input: JSON from step 2
• Extract relevant fields (recovery_score, hrv_rmssd_milli, sleep_performance_percentage, strain, heart_rate, etc.)
• Present in plain language (e.g. "Recovery: 82% (green)", "HRV: 54ms", "Sleep: 7h 42m")
• Output: formatted response to user

charting

step 1: call chart.py with chart type + duration

• Input: chart type (recovery, sleep, hrv, strain, dashboard), --days (default 30), --output (default /tmp/whoop-.html), --no-open flag (default false)
• Run: python3 scripts/chart.py --chart <type> --days <N> --output <path> [--no-open]
• Script fetches data via fetch.py (which handles token refresh), generates Chart.js HTML (dark theme, stat cards with avg/min/max + trend arrows)
• Output: self-contained static HTML file at specified path

step 2: deliver chart

• Always do both:
  1. Attach HTML file to message (local or remote user gets it instantly, no external server)
  2. Auto-open in browser on local machine (unless --no-open set)
• Output: user sees chart in browser + has file for sharing

experiment tracking

step 1: plan new experiment

• Input: experiment name, hypothesis, start date, end date, metrics list (hrv, recovery, sleep_performance, rhr, strain), optional baseline overrides
• Run: python3 scripts/experiment.py plan --name "..." --hypothesis "..." --start YYYY-MM-DD --end YYYY-MM-DD --metrics hrv,recovery,sleep_performance [--baseline-hrv 45.0 --baseline-rhr 58 ...]
• Script auto-captures baseline from 14 days before --start (unless manually overridden)
• Output: experiment created + stored in ~/.config/whoop-skill/experiments.json, unique ID returned

step 1b (optional): add post-workout segmentation

• Input: experiment (new or existing via --id), --segment-workouts flag, --min-strain (default 5.0), --days-after (default 1-2)
• Run: python3 scripts/experiment.py plan ... --segment-workouts --min-strain 5 --days-after 1-2
• OR on existing: python3 scripts/experiment.py add-segmentation --id <id> --min-strain 5 --days-after 1-2
• Script fetches workout history, filters by min-strain, measures recovery metrics in 24-48h windows after qualifying workouts
• Baseline is also segmented (only post-workout periods in the 14-day baseline window)
• Output: experiment marked with segmentation mode; post-workout baseline computed

step 2: check mid-experiment status

• Input: experiment ID
• Run: python3 scripts/experiment.py status --id <id>
• Script fetches current metrics from today back to experiment start, computes rolling averages vs baseline, calculates % change + trend
• If segmentation on: shows both overall view (all days) and post-workout view (only after qualifying workouts) with per-workout breakdown
• Output: formatted status report (current avg, baseline, % change, trend arrow)

step 3: final report

• Input: experiment ID
• Run: python3 scripts/experiment.py report --id <id>
• Script compares final period averages vs baseline
• Verdict: met / partially met / not met / inconclusive (evaluated on post-workout data if segmentation enabled)
• Output: before/after table, verdict, plain-language summary

obsidian logging (optional)

step 1: configure vault (one-time)

• Input: path to Obsidian vault directory
• Edit ~/.config/whoop-skill/config.json: set vault_path to vault directory (e.g. ~/my-obsidian-vault)
• Output: config saved; script will now auto-detect vault

step 2: log today's stats

• Input: vault_path configured + valid WHOOP credentials
• Run: python3 scripts/log_to_obsidian.py
• Script checks if vault exists, token is valid, fetches today's recovery/sleep/cycle data
• Creates or appends to <vault_path>/Daily Notes/YYYY-MM-DD.md
• Writes markdown table with recovery %, HRV, resting HR, sleep %, sleep duration, day strain
• If vault is git repo (.git folder exists): auto-stages, commits ("WHOOP log YYYY-MM-DD"), pushes
• If no git repo: silently skips git commands
• Output: daily note updated; git commit pushed (if applicable)

step 2b (optional): backfill past date

• Input: specific date (YYYY-MM-DD)
• Run: python3 scripts/log_to_obsidian.py --date 2026-03-01
• Script fetches stats for specified date, appends to that date's daily note
• Output: historical note updated

step 2c (optional): preview without writing

• Input: dry-run flag
• Run: python3 scripts/log_to_obsidian.py --dry-run
• Script prints formatted table to stdout but does not write file or push git
• Output: preview printed; no side effects

decision points

if access token expired (expires_at <= now + 60s):

• do: run python3 scripts/refresh_token.py
• else: proceed with existing access_token

if callback method is local server:

• do: spawn temporary HTTP server on localhost:8888, auto-catch redirect, extract code
• else (manual code paste): print authorization URL, prompt user to paste code from redirect URL

if obsidian vault_path is configured AND vault directory exists:

• do: after running any data fetch, optionally run scripts/log_to_obsidian.py to append to daily note
• else: skip Obsidian integration (no error, fully optional)

if obsidian vault has .git folder:

• do: commit and push changes (git add -A && git commit && git push)
• else: write note file only, skip all git commands (no errors)

if experiment has --segment-workouts enabled:

• do: evaluate verdict against post-workout recovery data only (filtered by min-strain, days-after window)
• do: show both overall averages (all days) and post-workout averages (only after qualifying workouts)
• else: evaluate verdict against overall daily averages

if chart.py --no-open is set:

• do: write HTML file but do not launch browser
• else: auto-open HTML file in default browser after writing

if fetch.py returns empty result set (limit reached but no data in range):

• do: return empty array; calling script handles presentation (e.g. "no data for this date range")
• else: return populated array

if API responds with 429 (rate limit):

• do: implement exponential backoff (2s, 4s, 8s) and retry up to 3 times
• else: return error and stop

if API responds with 401 (unauthorized, token revoked or expired):

• do: fail gracefully with message "credentials invalid or revoked; re-run auth.py"
• else: proceed normally

if network timeout (5s):

• do: retry once; if second attempt also times out, fail with "network error, check internet"
• else: return response

output contract

fetch.py:

• Output: JSON array of objects to stdout
• Each object contains fields from WHOOP API (id, created_at, updated_at, score{recovery_score, hrv_rmssd_milli, resting_heart_rate, ...}, etc.)
• Exit code 0 on success; non-zero + stderr message on auth failure, network error, or invalid endpoint
• File location: none (stdout only)

chart.py:

• Output: self-contained static HTML file (includes all Chart.js code + data inline, no external CDN calls)
• Location: --output path specified (default /tmp/whoop-.html)
• File is safe to share, contains no credentials or live API calls
• Dark theme, stat cards showing avg/min/max + trend arrows (up/down/flat)
• Chart types: recovery (bar, color-coded), sleep (stacked bar per night), hrv (line + 7-day rolling avg), strain (bar + secondary calories axis), dashboard (2x2 grid)
• Prints file path to stdout on completion
• Exit code 0 on success; non-zero + stderr on token expiry, API error, or fetch failure

experiment.py plan:

• Output: confirmation message with experiment ID + baseline stats
• Location: ~/.config/whoop-skill/experiments.json (persisted, can be backed up)
• Format: JSON object with fields: id (UUID), name, hypothesis, start_date, end_date, metrics[], baseline{hrv, recovery, rhr, ...}, segment_workouts (bool), min_strain (float), days_after (string), created_at
• Exit code 0 on success; non-zero + stderr on invalid metric, missing credentials, or file write error

experiment.py status:

• Output: formatted table with baseline, current avg, % change, trend arrow, (optionally) post-workout breakdown
• File location: none (stdout only)
• Format: plain text, markdown-compatible
• Exit code 0 on success; non-zero + stderr if experiment ID not found or fetch fails

experiment.py report:

• Output: before/after comparison table, verdict line (met/partially met/not met/inconclusive), plain-language summary
• File location: none (stdout only)
• Format: plain text, markdown-compatible
• Exit code 0 on success; non-zero + stderr if experiment ID not found or fetch fails

log_to_obsidian.py:

• Output: daily note file updated in vault
• Location: <vault_path>/Daily Notes/YYYY-MM-DD.md (as specified in config.json)
• Format: markdown table (| Metric | Value |) appended under "## 🏋️ WHOOP" heading
• Idempotent: if WHOOP section already exists for that day, skip silently
• If vault is git repo: new commit created (message "WHOOP log YYYY-MM-DD"), pushed to remote
• Exit code 0 on success; non-zero + stderr if vault_path missing/invalid, credentials invalid, or git push fails
• --dry-run prints formatted table to stdout, makes no changes, exit code 0

auth.py:

• Output: credentials file created
• Location: ~/.config/whoop-skill/credentials.json
• Format: JSON object with fields: client_id, client_secret, access_token, refresh_token, expires_at (unix timestamp), scope
• Exit code 0 on success; non-zero + stderr on invalid client ID/secret, redirect capture failure, network error, or file write error

refresh_token.py:

• Output: credentials file updated in place
• Location: ~/.config/whoop-skill/credentials.json
• New fields: access_token, expires_at (updated); refresh_token may rotate (updated if provided by API)
• Exit code 0 on success; non-zero + stderr on invalid refresh_token, network error, or file write error

outcome signal

fetch.py:

• User receives JSON on stdout (can be piped, parsed, or displayed)
• Data is current as of WHOOP's last sync with wearable (usually within minutes)
• If user sees valid metric values (recovery_score: 82, hrv_rmssd_milli: 54, etc.), skill worked

chart.py:

• HTML file created at specified path
• Browser auto-opens (unless --no-open set) and displays chart with title + stat cards
• User can see recovery bars color-coded (green/yellow/red), sleep stacked bars, HRV trend line, etc.
• If user can interact with chart (hover for data points, see stat card values), skill worked

experiment.py plan:

• Confirmation printed: "Experiment '' created with ID . Baseline captured from to ."
• If segmentation on: "Post-workout segmentation enabled: qualifying workouts found in baseline period."
• If user runs status or report commands later and gets results, skill worked

experiment.py status:

• Formatted table printed showing baseline avg, current avg, % change, trend arrow
• Example: "Recovery: baseline 72%, current 78%, +8.3% ↑"
• If segmentation on: post-workout view shows separately, e.g. "Post-workout recovery: baseline 65%, current 74%, +13.8% ↑"
• If user sees coherent numbers + trend, skill worked

experiment.py report:

• Verdict line printed: "Verdict: MET ✓" or "Verdict: PARTIALLY MET ~" etc.
• Summary paragraph in plain language (e.g. "Your hypothesis about HRV improvement was supported; 8 of 10 metrics trended up.")
• If user understands the verdict + summary, skill worked

log_to_obsidian.py:

• Daily note file created or updated in vault
• Table appended under "## 🏋️ WHOOP" heading with recovery %, HRV, resting HR, sleep %, duration, strain
• If vault is git repo: new commit visible in log (git log --oneline | head -1 shows "WHOOP log YYYY-MM-DD")
• If user opens daily note and sees formatted WHOOP section, or runs git log and sees commit, skill worked

auth.py:

• Credentials file exists at ~/.config/whoop-skill/credentials.json
• File contains valid access_token + expires_at
• If subsequent fetch.py call succeeds (returns data, not 401), skill worked

refresh_token.py:

• Credentials file updated (timestamp on file changes)
• New access_token differs from old one (check file content)
• If subsequent fetch.py call succeeds after refresh, skill worked

morning brief integration:

• If HEARTBEAT.md snippet is added, morning heartbeat runs fetch.py /recovery --limit 1 at 06:00-10:00 ET
• User sees "🏋️ Recovery: 82% 💚 | HRV: 54ms" in morning message
• If recovery < 34 (red), proactive mention appears
• If user receives formatted message at expected time, skill worked

---

references

• references/api.md , full WHOOP API endpoint reference, scopes, response shapes
• references/health_analysis.md , HRV ranges by age, resting HR interpretation, sleep stage targets, recovery zones, overtraining signals, when to see a doctor
• WHOOP Developer Dashboard: https://developer-dashboard.whoop.com
• WHOOP API docs: https://developer.whoop.com/api (official API reference, error codes, rate limits)

---

credits: original skill by paul brennaman (paulbrennaman.me/lab/whoop-skill). enriched and formalized per implexa standards.