fitbit-analytics – OpenClaw Skill

---

name: fitbit-analytics description: Fitbit health and fitness data integration. Fetch steps, heart rate, sleep, activity, calories, and trends from Fitbit Web API. Generate automated health reports and alerts. Requires FITBIT_CLIENT_ID, FITBIT_CLIENT_SECRET, FITBIT_ACCESS_TOKEN, FITBIT_REFRESH_TOKEN. metadata: {"openclaw":{"requires":{"bins":["python3"],"env":["FITBIT_CLIENT_ID","FITBIT_CLIENT_SECRET","FITBIT_ACCESS_TOKEN","FITBIT_REFRESH_TOKEN"]},"homepage":"https://github.com/kesslerio/fitbit-analytics-openclaw-skill"}}

Fitbit Analytics

Quick Start

# Set Fitbit API credentials
export FITBIT_CLIENT_ID="your_client_id"
export FITBIT_CLIENT_SECRET="your_client_secret"
export FITBIT_ACCESS_TOKEN="your_access_token"
export FITBIT_REFRESH_TOKEN="your_refresh_token"

# Generate morning briefing with Active Zone Minutes
python scripts/fitbit_briefing.py

# Fetch daily steps
python scripts/fitbit_api.py steps --days 7

# Get heart rate data
python scripts/fitbit_api.py heartrate --days 7

# Sleep summary
python scripts/fitbit_api.py sleep --days 7

# Generate weekly health report
python scripts/fitbit_api.py report --type weekly

# Get activity summary
python scripts/fitbit_api.py summary --days 7

When to Use

Use this skill when:

• Fetching Fitbit metrics (steps, calories, heart rate, sleep)
• Analyzing activity trends over time
• Setting up alerts for inactivity or abnormal heart rate
• Generating daily/weekly health reports

Core Workflows

1. Daily Briefing

# Generate morning health briefing (includes Active Zone Minutes)
python scripts/fitbit_briefing.py                    # Today's briefing
python scripts/fitbit_briefing.py --date 2026-01-20  # Specific date
python scripts/fitbit_briefing.py --format brief     # 3-line summary
python scripts/fitbit_briefing.py --format json      # JSON output

# Example output includes:
# - Yesterday's activities (logged exercises)
# - Yesterday's Active Zone Minutes (total, Fat Burn, Cardio, Peak)
# - Today's activity summary (steps, calories, floors, distance)
# - Heart rate (resting, average, zones)
# - Sleep (duration, efficiency, awake episodes)
# - Trends vs 7-day average

Example JSON output:

{
  "date": "2026-01-21",
  "steps_today": 8543,
  "calories_today": 2340,
  "distance_today": 6.8,
  "floors_today": 12,
  "active_minutes": 47,
  "resting_hr": 58,
  "avg_hr": 72,
  "sleep_hours": 7.2,
  "sleep_efficiency": 89,
  "awake_minutes": 12,
  "yesterday_activities": [
    {"name": "Run", "duration": 35, "calories": 320}
  ],
  "yesterday_azm": {
    "activeZoneMinutes": 61,
    "fatBurnActiveZoneMinutes": 39,
    "cardioActiveZoneMinutes": 22
  }
}

Note: Cardio Load is NOT available via Fitbit API - it's a Fitbit Premium feature only visible in the mobile app.

2. Data Fetching (CLI)

# Available commands:
python scripts/fitbit_api.py steps --days 7
python scripts/fitbit_api.py calories --days 7
python scripts/fitbit_api.py heartrate --days 7
python scripts/fitbit_api.py sleep --days 7
python scripts/fitbit_api.py summary --days 7
python scripts/fitbit_api.py report --type weekly

3. Data Fetching (Python API)

export PYTHONPATH="{baseDir}/scripts"
python - <<'PY'
from fitbit_api import FitbitClient

client = FitbitClient()  # Uses env vars for credentials

# Fetch data (requires start_date and end_date)
steps_data = client.get_steps(start_date="2026-01-01", end_date="2026-01-16")
hr_data = client.get_heartrate(start_date="2026-01-01", end_date="2026-01-16")
sleep_data = client.get_sleep(start_date="2026-01-01", end_date="2026-01-16")
activity_summary = client.get_activity_summary(start_date="2026-01-01", end_date="2026-01-16")
PY

4. Analysis

export PYTHONPATH="{baseDir}/scripts"
python - <<'PY'
from fitbit_api import FitbitAnalyzer

analyzer = FitbitAnalyzer(steps_data, hr_data)
summary = analyzer.summary()
print(summary)  # Returns: avg_steps, avg_resting_hr, step_trend
PY

5. Alerts

python {baseDir}/scripts/alerts.py --days 7 --steps 8000 --sleep 7

Scripts

• scripts/fitbit_api.py - Fitbit Web API wrapper, CLI, and analysis
• scripts/fitbit_briefing.py - Morning briefing CLI (text/brief/json output)
• scripts/alerts.py - Threshold-based notifications

Available API Methods

Method	Description
get_steps(start, end)	Daily step counts
get_calories(start, end)	Daily calories burned
get_distance(start, end)	Daily distance
get_activity_summary(start, end)	Activity summary
get_heartrate(start, end)	Heart rate data
get_sleep(start, end)	Sleep data
get_sleep_stages(start, end)	Detailed sleep stages
get_spo2(start, end)	Blood oxygen levels
get_weight(start, end)	Weight measurements
get_active_zone_minutes(start, end)	Active Zone Minutes (AZM) breakdown

References

• references/api.md - Fitbit Web API documentation
• references/metrics.md - Metric definitions and interpretations

Authentication

Fitbit API requires OAuth 2.0 authentication:

1. Create app at: https://dev.fitbit.com/apps
2. Get client_id and client_secret
3. Complete OAuth flow to get access_token and refresh_token
4. Set environment variables or pass to scripts

Environment

Required:

• FITBIT_CLIENT_ID
• FITBIT_CLIENT_SECRET
• FITBIT_ACCESS_TOKEN
• FITBIT_REFRESH_TOKEN

Automation (Cron Jobs)

Cron jobs are configured in OpenClaw's gateway, not in this repo. Add these to your OpenClaw setup:

Daily Morning Briefing (8:00 AM)

openclaw cron add \
  --name "Morning Fitbit Health Report" \
  --cron "0 8 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --deliver \
  --channel telegram \
  --target "<YOUR_TELEGRAM_CHAT_ID>" \
  --message "python3 /path/to/your/scripts/fitbit_briefing.py --format text"

Note: Replace /path/to/your/ with your actual path and <YOUR_TELEGRAM_CHAT_ID> with your Telegram channel/group ID.

Fitbit Analytics Skill for OpenClaw 🦞

Fitbit health and fitness data integration for OpenClaw. Fetch steps, heart rate, sleep, activity, calories, and trends from Fitbit Web API. Generate automated health reports, correlations, and alerts.

Features

• Activity Tracking: Fetch daily steps, distance, calories, and active minutes.
• Heart Rate: Access continuous heart rate data and resting heart rate trends.
• Sleep Analytics: Analyze sleep stages (Deep, Light, REM, Wake) and efficiency.
• Reports: Generate daily/weekly health reports with trend analysis.
• Automation: Scripts ready for cron jobs (e.g., daily summaries).

Setup

1. Create a Fitbit Developer App

1. Go to dev.fitbit.com/apps and log in.
2. Click "Register an App".
3. Fill in the details:
   • Application Name: Personal Assistant (or your choice)
   • Description: Personal AI analytics.
   • OAuth 2.0 Application Type: Personal
   • Redirect URL: http://localhost:8080/
   • Default Access Type: Read & Write
4. Save and note your Client ID and Client Secret.

2. Configure Credentials

Add keys to your secrets.conf or environment variables:

export FITBIT_CLIENT_ID="YOUR_CLIENT_ID"
export FITBIT_CLIENT_SECRET="YOUR_CLIENT_SECRET"

3. Authorization Flow

1. Construct the URL:

   https://www.fitbit.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2F&scope=activity%20heartrate%20location%20nutrition%20profile%20settings%20sleep%20social%20weight&expires_in=604800
   

2. Authorize in browser.
3. Copy the code from the redirect URL (http://localhost:8080/?code=...).
4. Exchange code for tokens:

   curl -X POST https://api.fitbit.com/oauth2/token \
     -u "CLIENT_ID:CLIENT_SECRET" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=YOUR_CODE" \
     -d "redirect_uri=http://localhost:8080/"
   

5. Save access_token and refresh_token to FITBIT_ACCESS_TOKEN and FITBIT_REFRESH_TOKEN.

Usage

Note: For Python imports, set PYTHONPATH to the scripts/ folder:

export PYTHONPATH="$(pwd)/scripts"

Fetch Daily Stats

# Get steps for today
python scripts/fitbit_api.py steps --days 1

# Get sleep data
python scripts/fitbit_api.py sleep --days 1

Generate Weekly Report

python scripts/fitbit_api.py report --type weekly

Daily Morning Briefing

# Text format (for Telegram)
python scripts/fitbit_briefing.py --format text

# Brief format (3-line summary)
python scripts/fitbit_briefing.py --format brief

# JSON format (for programmatic use)
python scripts/fitbit_briefing.py --format json

Example brief output:

📊 8,543 steps • 2,340 cal
❤️ Resting HR: 58 • 💤 7.2h sleep
🏃 Moderate • ↑ 12% vs avg

Example JSON output:

{
  "date": "2026-01-21",
  "steps_today": 8543,
  "calories_today": 2340,
  "distance_today": 6.8,
  "floors_today": 12,
  "active_minutes": 47,
  "resting_hr": 58,
  "avg_hr": 72,
  "sleep_hours": 7.2,
  "sleep_efficiency": 89,
  "awake_minutes": 12,
  "activity_level": "Moderate",
  "steps_trend": 12,
  "yesterday_azm": {
    "activeZoneMinutes": 61,
    "fatBurnActiveZoneMinutes": 39,
    "cardioActiveZoneMinutes": 22
  }
}

Structure

• scripts/fitbit_api.py: Main API wrapper and CLI tool.
• scripts/fitbit_briefing.py: Morning briefing CLI (text/brief/json output).
• scripts/alerts.py: Threshold-based notifications.
• references/: API and metrics documentation.
• docs/: Privacy Policy and Terms of Service.

License

Apache 2.0