whoopskill – OpenClaw Skill

---

name: whoopskill description: WHOOP CLI with health insights, trends analysis, and data fetching (sleep, recovery, HRV, strain). homepage: https://github.com/koala73/whoopskill metadata: {"clawdis":{"emoji":"💪","requires":{"bins":["node"],"env":["WHOOP_CLIENT_ID","WHOOP_CLIENT_SECRET","WHOOP_REDIRECT_URI"]},"install":[{"id":"npm","kind":"npm","package":"whoopskill","bins":["whoopskill"],"label":"Install whoopskill (npm)"}]}}

whoopskill

Use whoopskill to fetch WHOOP health metrics (sleep, recovery, HRV, strain, workouts).

Install: npm install -g whoopskill | GitHub

Quick start

• whoopskill summary — one-liner: Recovery: 52% | HRV: 39ms | Sleep: 40% | Strain: 6.7
• whoopskill summary --color — color-coded summary with 🟢🟡🔴 status indicators
• whoopskill trends — 7-day trends with averages and direction arrows
• whoopskill trends --days 30 --pretty — 30-day trend analysis
• whoopskill insights --pretty — AI-style health recommendations
• whoopskill --pretty — human-readable output with emojis
• whoopskill recovery — recovery score, HRV, RHR
• whoopskill sleep — sleep performance, stages
• whoopskill workout — workouts with strain
• whoopskill --date 2025-01-03 — specific date

Analysis commands

• summary — quick health snapshot (add --color for status indicators)
• trends — multi-day averages with trend arrows (↑↓→)
• insights — personalized recommendations based on your data

Data types

• profile — user info (name, email)
• body — height, weight, max HR
• sleep — sleep stages, efficiency, respiratory rate
• recovery — recovery %, HRV, RHR, SpO2, skin temp
• workout — strain, HR zones, calories
• cycle — daily strain, calories

Combine types

• whoopskill --sleep --recovery --body

Auth

• whoopskill auth login — OAuth flow (opens browser)
• whoopskill auth status — check token status
• whoopskill auth logout — clear tokens

Notes

• Output is JSON to stdout (use --pretty for human-readable)
• Tokens stored in ~/.whoop-cli/tokens.json (auto-refresh)
• Uses WHOOP API v2
• Date follows WHOOP day boundary (4am cutoff)
• WHOOP apps with <10 users don't need review (immediate use)

Sample: whoopskill summary --color

📅 2026-01-25
🟢 Recovery: 85% | HRV: 39ms | RHR: 63bpm
🟡 Sleep: 79% | 6.9h | Efficiency: 97%
🔴 Strain: 0.1 (optimal: ~14) | 579 cal

Sample: whoopskill trends

📊 7-Day Trends

💚 Recovery: 62.1% avg (34-86) →
💓 HRV: 33.8ms avg (26-42) →
❤️ RHR: 63.8bpm avg (60-68) →
😴 Sleep: 75.4% avg (69-79) →
🛏️ Hours: 6.5h avg (5.7-7.8) ↓
🔥 Strain: 5.9 avg (0.1-9.0) ↓

Sample: whoopskill insights

💡 Insights & Recommendations

✅ Green Recovery
   Recovery at 85% — body is primed for high strain.
   → Great day for intense training or competition.

✅ HRV Above Baseline
   Today's HRV (39ms) is 21% above your 7-day average.
   → Excellent recovery. Good day for peak performance.

⚠️ Mild Sleep Debt
   You have 2.0 hours of sleep debt.
   → Consider an earlier bedtime tonight.

✅ Strain Capacity Available
   Current strain: 0.1. Optimal target: ~14.
   → Room for 13.9 more strain today.

Sample: whoopskill --sleep --recovery (JSON)

{
  "date": "2026-01-05",
  "fetched_at": "2026-01-05T13:49:22.782Z",
  "body": {
    "height_meter": 1.83,
    "weight_kilogram": 82.5,
    "max_heart_rate": 182
  },
  "sleep": [
    {
      "id": "4c311bd4-370f-49ff-b58c-0578d543e9d2",
      "cycle_id": 1236731435,
      "user_id": 245199,
      "created_at": "2026-01-05T00:23:34.264Z",
      "updated_at": "2026-01-05T02:23:54.686Z",
      "start": "2026-01-04T19:51:57.280Z",
      "end": "2026-01-05T01:30:48.660Z",
      "timezone_offset": "+04:00",
      "nap": false,
      "score_state": "SCORED",
      "score": {
        "stage_summary": {
          "total_in_bed_time_milli": 20331380,
          "total_awake_time_milli": 4416000,
          "total_light_sleep_time_milli": 6968320,
          "total_slow_wave_sleep_time_milli": 4953060,
          "total_rem_sleep_time_milli": 3994000,
          "sleep_cycle_count": 4,
          "disturbance_count": 4
        },
        "sleep_needed": {
          "baseline_milli": 26783239,
          "need_from_sleep_debt_milli": 6637715,
          "need_from_recent_strain_milli": 148919
        },
        "respiratory_rate": 14.12,
        "sleep_performance_percentage": 40,
        "sleep_consistency_percentage": 60,
        "sleep_efficiency_percentage": 78.28
      }
    }
  ],
  "workout": [
    {
      "id": "4279883e-3d23-45cd-848c-3afa28dca3f8",
      "user_id": 245199,
      "start": "2026-01-05T03:14:13.417Z",
      "end": "2026-01-05T04:06:45.532Z",
      "sport_name": "hiit",
      "score_state": "SCORED",
      "score": {
        "strain": 6.19,
        "average_heart_rate": 108,
        "max_heart_rate": 144,
        "kilojoule": 819.38,
        "zone_durations": {
          "zone_zero_milli": 167000,
          "zone_one_milli": 1420000,
          "zone_two_milli": 1234980,
          "zone_three_milli": 330000,
          "zone_four_milli": 0,
          "zone_five_milli": 0
        }
      }
    }
  ],
  "profile": {
    "user_id": 245199,
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recovery": [
    {
      "cycle_id": 1236731435,
      "sleep_id": "4c311bd4-370f-49ff-b58c-0578d543e9d2",
      "user_id": 245199,
      "score_state": "SCORED",
      "score": {
        "recovery_score": 52,
        "resting_heart_rate": 60,
        "hrv_rmssd_milli": 38.87,
        "spo2_percentage": 96.4,
        "skin_temp_celsius": 33.19
      }
    }
  ],
  "cycle": [
    {
      "id": 1236731435,
      "user_id": 245199,
      "start": "2026-01-04T19:51:57.280Z",
      "end": null,
      "score_state": "SCORED",
      "score": {
        "strain": 6.66,
        "kilojoule": 6172.94,
        "average_heart_rate": 71,
        "max_heart_rate": 144
      }
    }
  ]
}

WHOOP Skill

CLI for fetching WHOOP health data via the WHOOP API v2.

Install

npm install -g whoopskill

Quick Start

# One-liner health snapshot
whoopskill summary
# Output: 2026-01-05 | Recovery: 52% | HRV: 39ms | RHR: 60 | Sleep: 40% | Strain: 6.7

# Human-readable output
whoopskill --pretty

# JSON output (default)
whoopskill

Setup

Before using, you need to configure WHOOP API credentials:

1. Register a WHOOP application at developer.whoop.com

   • Apps with <10 users don't need WHOOP review (immediate use)

2. Set environment variables:

export WHOOP_CLIENT_ID=your_client_id
export WHOOP_CLIENT_SECRET=your_client_secret
export WHOOP_REDIRECT_URI=https://your-redirect-uri.com/callback

Or create a .env file in your working directory.

3. Authenticate:

whoopskill auth login

Tokens are stored in ~/.whoop-cli/tokens.json and auto-refresh when expired.

Usage

# Fetch all today's data
whoopskill

# One-liner health snapshot
whoopskill summary

# Human-readable output
whoopskill --pretty

# Specific data type
whoopskill profile
whoopskill body
whoopskill sleep
whoopskill recovery
whoopskill workout
whoopskill cycle

# Multiple types
whoopskill --sleep --recovery --body

# Specific date (ISO format)
whoopskill --date 2025-01-03

# Pagination
whoopskill workout --limit 50
whoopskill workout --all

Auth Commands

whoopskill auth login    # OAuth flow (opens browser)
whoopskill auth status   # Check token status
whoopskill auth refresh  # Refresh access token using refresh token
whoopskill auth logout   # Clear tokens

Keeping tokens fresh (recommended for cron/servers)

If you run whoopskill from cron/systemd, you may occasionally see authentication failures if a token refresh is missed or the token file becomes stale.

Important:

• whoopskill auth status does not refresh tokens — it only reports whether they’re expired.
• For automation, you must call whoopskill auth refresh periodically.

Recommended pattern:

• Run whoopskill auth login once interactively (creates ~/.whoop-cli/tokens.json).
• Run a small periodic monitor that calls whoopskill auth refresh and performs a lightweight fetch.

An example monitor script + systemd timer/cron examples are included here:

• examples/monitor/whoop-refresh-monitor.sh
• examples/monitor/systemd/*
• examples/monitor/cron/README-cron.txt

If refresh fails with an expired refresh token, you must re-authenticate:

whoopskill auth login

Data Types

Type	Description
profile	User info (name, email)
body	Body measurements (height, weight, max HR)
sleep	Sleep records with stages, efficiency, respiratory rate
recovery	Recovery score, HRV, RHR, SpO2, skin temp
workout	Workouts with strain, HR zones, calories
cycle	Daily physiological cycle (strain, calories)

Options

Flag	Description
-d, --date <date>	Date in ISO format (YYYY-MM-DD)
-l, --limit <n>	Max results per page (default: 25)
-a, --all	Fetch all pages
-p, --pretty	Human-readable output
--profile	Include profile
--body	Include body measurements
--sleep	Include sleep
--recovery	Include recovery
--workout	Include workouts
--cycle	Include cycle

Output

JSON to stdout by default. Use --pretty for human-readable format.

{
  "date": "2025-01-05",
  "fetched_at": "2025-01-05T12:00:00.000Z",
  "profile": { "user_id": 123, "first_name": "John" },
  "body": { "height_meter": 1.83, "weight_kilogram": 82.5, "max_heart_rate": 182 },
  "recovery": [{ "score": { "recovery_score": 52, "hrv_rmssd_milli": 38.9 }}],
  "sleep": [{ "score": { "sleep_performance_percentage": 40 }}],
  "workout": [{ "sport_name": "hiit", "score": { "strain": 6.2 }}],
  "cycle": [{ "score": { "strain": 6.7 }}]
}

Exit Codes

Code	Meaning
0	Success
1	General error
2	Authentication error
3	Rate limit exceeded
4	Network error

Requirements

• Node.js 22+
• WHOOP membership with API access

Development

git clone https://github.com/koala73/whoopskill.git
cd whoopskill
npm install
npm run dev      # Run with tsx
npm run build    # Compile TypeScript

License

MIT