Fitbit Tracker

Personal Fitbit integration for daily health tracking with adaptive sleep and activity reporting

Security Scan

The skill's code, instructions, and required environment variables are consistent with a local Fitbit OAuth integration and do what the description says; nothing in the bundle indicates unexplained access or hidden exfiltration.

Purpose & Capability

Name/description (Fitbit integration) match the included scripts and docs. Required binaries (python3), required env vars (FITBIT_CLIENT_ID, FITBIT_CLIENT_SECRET, FITBIT_REDIRECT_URI, optional FITBIT_TZ) are appropriate for OAuth-based Fitbit API access.

Instruction Scope

SKILL.md instructs the agent to run the included scripts (oauth login, fetch, normalize, render). Those scripts only access Fitbit endpoints (api.fitbit.com), local token files, and local temp files; they do not reference unrelated system files, other credentials, or external endpoints beyond Fitbit.

Install Mechanism

No install spec; this is an instruction-only skill with bundled Python scripts that rely on the standard library only. Nothing is downloaded from third-party URLs or installed silently.

Credentials

Declared environment variables are exactly the OAuth client ID/secret/redirect URI and an optional timezone; these are necessary and proportionate. The scripts only read these vars (and optionally FITBIT_SCOPES and FITBIT_TOKEN_PATH) as expected.

Persistence & Privilege

always is false and the skill does not request persistent platform privileges. It stores tokens to a local path (~/.config/openclaw/fitbit/token.json by default) which is normal for an OAuth client; it does not modify other skills or global agent settings.

Assessment

This skill appears to do what it says: a local Fitbit OAuth client and renderer. Before installing, ensure you: (1) create a Fitbit developer app and keep the Client Secret private; (2) set FITBIT_REDIRECT_URI to a safe local URL (loopback) or your chosen redirect endpoint; (3) understand tokens will be stored on disk by default at ~/.config/openclaw/fitbit/token.json (you can override with FITBIT_TOKEN_PATH); (4) review scopes (activity, sleep, heartrate, profile, weight) and only grant what you are comfortable sharing; and (5) be aware the scripts will make network calls to api.fitbit.com and respect Fitbit rate limits. If you need higher assurance, inspect the token file after authentication and verify file permissions (save_token attempts 0o600).

Effortless health monitoring powered by the official Fitbit API. No apps, no dashboards — just ask and get your health stats instantly.

Features

Smart Sleep Tracking

• Automatically separates naps from main sleep
• Reports duration, efficiency, and all sleep stages (Deep, Light, REM, Wake)
• Nap detection with separate reporting

Complete Activity Picture

• Steps, calories, distance, active minutes
• Resting heart rate
• Heart rate zones (Out of Range, Fat Burn, Cardio, Peak)

Adaptive Reporting

Only shows what you ask for — no unnecessary data.

You say...	Reports...
"how did I sleep" / "sleep"	Duration, efficiency, all stages, nap
"just my steps"	Steps only
"activity today"	Steps, calories, distance, active mins, HR zones
"full report" / "everything" / "summary"	All available data
"fitbit" / "health"	Complete daily summary

Clean Formatting

• Numbers formatted for readability (e.g., "8,234 steps")
• Stages grouped logically
• No raw data dumps

Data Available

Sleep:

• Duration (total sleep time)
• Sleep efficiency %
• Sleep score (when available)
• Sleep stages: Deep, Light, REM, Wake
• Nap duration (when taken)

Activity:

• Steps
• Calories (total + BMR)
• Distance (km)
• Resting heart rate
• Active minutes (Very Active, Fairly, Lightly, Sedentary)
• Heart rate zones

Setup

1. Create Fitbit Developer App

1. Go to dev.fitbit.com
2. Log in and click Register an App
3. Fill in:
   • Application Name: OpenClaw Fitbit (or any name)
   • Description: Fitbit integration for OpenClaw
   • Application Website: https://github.com/yourusername/openclaw
   • OAuth 2.0 Application Type: Choose Personal
   • Callback URL: http://localhost:8080 (for local) or your redirect URI
4. Accept the terms and register
5. Copy your Client ID and Client Secret

2. Configure Environment Variables

export FITBIT_CLIENT_ID="your_client_id"
export FITBIT_CLIENT_SECRET="your_client_secret"
export FITBIT_REDIRECT_URI="http://localhost:8080"
export FITBIT_TZ="Europe/London"  # Your timezone

Or add to ~/.openclaw/.env:

FITBIT_CLIENT_ID=your_client_id
FITBIT_CLIENT_SECRET=your_client_secret
FITBIT_REDIRECT_URI=http://localhost:8080
FITBIT_TZ=Europe/London

3. Authenticate

Run the OAuth login script:

python3 scripts/fitbit_oauth_login.py

This will:

• Open Fitbit authorization page in your browser
• Ask you to approve access
• Exchange the code for tokens
• Save tokens to ~/.config/openclaw/fitbit/token.json

Tokens are automatically refreshed when they expire.

Commands

The skill uses a 3-step pipeline:

# Step 1: Fetch raw data from Fitbit API
# IMPORTANT: For sleep queries (morning), use --date today not yesterday!
# Fitbit returns last night's sleep under today's date.
python3 scripts/fitbit_fetch_daily.py --date today --out /tmp/fitbit_raw.json

# Step 2: Normalize into clean format (extracts actual sleep time, stages, activity)
python3 scripts/fitbit_normalize_daily.py /tmp/fitbit_raw.json --out /tmp/fitbit_day.json

# Step 3: Render for display (use --channel discord, telegram, or generic)
python3 scripts/fitbit_render.py /tmp/fitbit_day.json --channel discord

For a specific date (YYYY-MM-DD format):

python3 scripts/fitbit_fetch_daily.py --date 2026-03-25 --out /tmp/fitbit_raw.json

For sleep section only:

python3 scripts/fitbit_render.py /tmp/fitbit_day.json --channel discord --section sleep

Critical date rule: When user asks about sleep in the morning (e.g., "how did I sleep"), use --date today. Fitbit's sleep API associates sleep with the date you woke up, so last night's sleep (Mar 25 11pm → Mar 26 7am) appears under date "today" (Mar 26). Only use --date yesterday for activity-only queries when you specifically want the previous full day's activity data.

Important: Always run the full pipeline (fetch → normalize → render). Never use raw API duration field directly — it includes wake periods inside the sleep window. The normalized duration_minutes field (which maps to Fitbit's minutesAsleep) is the actual sleep time.

Usage Examples

Sleep report:

Fitbit — 2026-03-21
- Sleep: 7h 32m (score 85) | 93% efficiency
  - Stages: Deep: 1h 42m, Light: 3h 20m, REM: 1h 45m, Wake: 45m
- Nap: 1h 6m

Full daily summary:

Fitbit — 2026-03-21
- Sleep: 7h 32m (score 85) | 93% efficiency
  - Stages: Deep: 1h 42m, Light: 3h 20m, REM: 1h 45m, Wake: 45m
- Nap: 1h 6m
- Steps: 8,234
- Calories: 1,892 (1,048 BMR)
- Distance: 6.2 km
- Resting HR: 58 bpm
  - Active mins: V. Active: 45m, Fair: 23m, Light: 1h 24m, Sedentary: 8h 12m
  - HR Zones: Out of Range: 12h, Fat Burn: 1h 30m, Cardio: 32m, Peak: 8m

Steps only:

- Steps: 8,234

Python Dependencies

No third-party dependencies required. Uses Python standard library:

• urllib.request - HTTP requests
• json - JSON parsing
• datetime - Date handling
• zoneinfo - Timezone support (Python 3.9+)

Troubleshooting

"Missing env var: FITBIT_CLIENT_ID"

Environment variables not loaded. Source your .env file or ensure variables are set in the gateway environment:

source ~/.openclaw/.env

"Token expired" error

Tokens auto-refresh. If you see this error repeatedly:

1. Delete ~/.config/openclaw/fitbit/token.json
2. Re-run python3 scripts/fitbit_oauth_login.py

"No data found for this day"

• Check FITBIT_TZ matches your timezone
• Try --date yesterday to confirm data exists
• Verify Fitbit account has data for the date

Nap not separating from main sleep

This may indicate isMainSleep flag isn't set correctly on your Fitbit account. The skill filters records by this flag — some older Fitbit devices don't set it properly.

Sleep score not showing

Not all Fitbit accounts/devices provide sleep scores. This is a Fitbit API limitation, not the skill. Efficiency and stages are always reported when available.

API Endpoints Used

• GET /1/user/-/activities/date/{date}.json - Daily activity summary
• GET /1.2/user/-/sleep/date/{date}.json - Sleep records

References

• API details: references/fitbit_api.md
• Output schema: references/output_schema.md