WHOOP Skill

Fetch, interpret, chart, and track your WHOOP data via the WHOOP Developer API (v2).

Data Directory

All user-specific data is stored in ~/.config/whoop-skill/ — separate from the skill install directory, which is read-only.

CODEBLOCK0

The directory and credentials.json are created automatically when you run scripts/auth.py. You never need to create them manually.

Setup

Before you begin: This skill requires a WHOOP Developer App to authenticate with the WHOOP API. It's free and takes about 2 minutes to set up.

Step 0 — Install Python dependencies

CODEBLOCK1

Step 1 — Choose your callback method

Before creating your WHOOP app, decide how you want to handle the OAuth callback:

Option A — Local server (local installs)

• - Redirect URI: INLINECODE3
• A temporary server runs on your machine to catch the redirect automatically
• Requires a browser on the same machine as OpenClaw

Option B — Manual code paste (remote/cloud installs)

• - Redirect URI: INLINECODE4
• The script prints an authorization URL — open it in any browser, authorize, then copy the ?code= value from the redirect URL and paste it back into the script
• Nothing passes through any external server — fully self-contained

Step 2 — Create a WHOOP Developer App

1. 1. Go to https://developer-dashboard.whoop.com
2. Sign in with your WHOOP account
3. Create a Team if prompted (any name works)
4. Click Create App and fill in:

1. 5. Copy your Client ID and Client Secret — you'll need them in the next step

Step 3 — Run the setup script

CODEBLOCK2

This will:

1. 1. Prompt you for your Client ID and Client Secret
2. Ask which callback method you chose in Step 1 (local server or manual)
3. Walk you through the authorization flow
4. Save credentials to INLINECODE8

Customize paths (optional):
Copy config.example.json from the skill root to ~/.config/whoop-skill/config.json and edit to override defaults:
CODEBLOCK3

Workflow

1. 1. Load credentials from INLINECODE11
2. If expires_at is in the past (or within 60s), call scripts/refresh_token.py to get a new access token and update the file
3. Call the appropriate endpoint (see references/api.md)
4. Parse and present the data in plain language

Common Requests

• - "How's my recovery today?" → GET latest recovery score, HRV, RHR
• "How did I sleep?" → GET latest sleep (performance %, stages, duration)
• "What's my strain today?" → GET latest cycle strain + avg HR
• "Show my recent workouts" → GET workout collection (last 5–7) via INLINECODE15
• "Give me a health summary" → Combine recovery + sleep + today's cycle

Token Refresh

Run scripts/refresh_token.py when the access token is expired. It reads/writes ~/.config/whoop-skill/credentials.json automatically.

To re-auth from scratch, run scripts/auth.py again.

API Base URL

INLINECODE19

All requests: INLINECODE20

See references/api.md for endpoint details, scopes, and response shapes. For the full official API documentation (including error codes and rate limits), see https://developer.whoop.com/api.

Fetching Data (scripts/fetch.py)

General-purpose API fetcher. Used internally by other scripts.

CODEBLOCK4

Output is JSON to stdout.

Charting (scripts/chart.py)

Generates self-contained HTML charts using Chart.js (CDN). Dark theme with stat cards showing avg/min/max + trend arrow. Opens in browser automatically.

Chart Types

Usage

CODEBLOCK5

Flags

Chart Delivery (always do both)

After running chart.py, the script prints the output file path to stdout. Always:

1. 1. Attach the HTML file to the Telegram message — so remote users get it instantly
2. Auto-open in browser (default, unless --no-open) — so local users get it immediately

This means both local and remote users are covered without any configuration. The file is self-contained, static, and safe to share — no credentials or API calls embedded.

Experiment Tracking (scripts/experiment.py)

Define, monitor, and evaluate personal health experiments. Data stored in ~/.config/whoop-skill/experiments.json.

Supported Metrics

INLINECODE38, recovery, sleep_performance, rhr, INLINECODE42

Commands

Plan a new experiment

Baseline is auto-captured from the 14 days before --start. Override manually:
CODEBLOCK7

Plan with post-workout segmentation

Use --segment-workouts when your hypothesis is specifically about recovery after training sessions rather than overall daily averages. The tracker will fetch your workout history, identify qualifying sessions, and measure recovery metrics only in the 24–48h window after each workout.

CODEBLOCK8

Flags:

• - --segment-workouts — enables post-workout segmentation mode
• INLINECODE46 — minimum workout strain to qualify (default: 5.0). Filters out light activity like walking or yoga.
• INLINECODE47 — recovery window to measure, e.g. 1-2 (days 1 and 2 after workout) or 1 (next day only). Default: INLINECODE50

When segmentation is on, status and report show two views: overall rolling averages (all days) and post-workout recovery (only the days after qualifying workouts). The verdict is evaluated against the post-workout view.

The post-workout baseline is also segmented — auto-captured from qualifying workouts in the 14 days before --start — so the comparison is apples-to-apples.

Add segmentation to an existing experiment

Patches a previously created experiment to add post-workout segmentation and recomputes the post-workout baseline from the original baseline window.

List experiments

Check status (mid-experiment)

python3 scripts/experiment.py status --id <id>

Final report

python3 scripts/experiment.py report --id <id>

Obsidian Logging (scripts/log_to_obsidian.py) (optional)

This feature is entirely optional. If you don't use Obsidian, skip this section — the rest of the skill works without it. To enable it, set vault_path in ~/.config/whoop-skill/config.json to your Obsidian vault directory. The script will not run if no vault is configured.

Note: git is declared as a dependency because the script calls git commands, but it is only ever invoked if your Obsidian vault is a git repository. If the vault directory has no .git folder, the script detects this, writes the daily note, and skips all git commands — no errors, no git required in practice.

Appends today's WHOOP stats to the Obsidian daily note at:
<vault_path>/Daily Notes/YYYY-MM-DD.md (configured via vault_path in ~/.config/whoop-skill/config.json)

After writing, commits and pushes the vault (git add -A && git commit && git push).

Usage

CODEBLOCK13

Output format in daily note

CODEBLOCK14

• - Creates the daily note if it doesn't exist
• Skips silently if the WHOOP section already exists
• Idempotent — safe to run multiple times

Morning Brief Integration

Add the following snippet to HEARTBEAT.md to include WHOOP recovery + HRV in morning briefs.

CODEBLOCK15

Copy-paste ready HEARTBEAT.md snippet:

CODEBLOCK16

Health Interpretation

See references/health_analysis.md for a science-backed guide covering:

• - HRV (RMSSD) ranges by age, what trends mean, red flags
• Resting heart rate interpretation by fitness level
• Sleep stage breakdown (deep/REM/light targets, deficit consequences)
• Recovery score zones (green/yellow/red) and recommended actions
• Strain scale and how to match strain to recovery
• SpO2 and skin temperature context
• Overtraining pattern recognition
• When to see a doctor

References

• - references/api.md — Full WHOOP API endpoint reference
• INLINECODE66 — Health metric interpretation guide
• WHOOP Developer Dashboard: https://developer-dashboard.whoop.com
• WHOOP API docs: https://developer.whoop.com/api