Wahoo Cloud Skill

Provides programmatic access to Wahoo Fitness Cloud data. This skill manages OAuth2 authentication, workout synchronization, and FIT file processing.

🚀 Agent Quickstart

When a user asks about their Wahoo workouts, training, or fitness data, use these workflows:

🛠 Key Workflows

1. Authentication & Setup

This skill requires a Wahoo Developer App.

• Credentials: Must be provided as WAHOO_CLIENT_ID and WAHOO_CLIENT_SECRET.
• OAuth Flow: If tokens are missing or expired, run scripts/oauth_setup.py. This is an interactive process. You must present the URL to the user, wait for them to authenticate, and then ask them to paste the resulting redirect URL/code back into the terminal.
• Token Storage: Tokens are stored at $WAHOO_BASE_DIR/secrets/wahoo_tokens.json (controlled by WAHOO_BASE_DIR env var, default ~/.wahoo).

2. Data Synchronization

• Command: python3 scripts/fetch_workouts.py
• Behavior: Idempotent. It fetches new workouts, downloads FIT files, and populates the local SQLite database.
• Database Path: $WAHOO_BASE_DIR/wahoo.db (default: ~/.wahoo/wahoo.db)
• Rate Limits: The script automatically handles Wahoo's sandbox rate limits (25 req / 5 min) using exponential backoff.

3. Querying Training Data

Once synced, use the following SQL patterns to answer user questions:

• Recent Workouts: SELECT * FROM workouts ORDER BY starts DESC LIMIT 10;
• Power/HR Series: SELECT timestamp, power_w, heart_rate, cadence FROM records WHERE workout_id = ORDER BY timestamp;
• Elevation/GPS: SELECT timestamp, position_lat_deg, position_long_deg, enhanced_altitude_m FROM records WHERE workout_id = ;

⚠️ Critical Constraints & Pitfalls

• Rate Limiting: Wahoo Sandbox is strict. Do not attempt to loop calls rapidly; rely on the wahoo_api.py built-in backoff.
• Data Types: The Wahoo API returns decimal values as strings. Always cast to float() before performing mathematical analysis.
• Metric Conversion:
• Meters to Miles: m / 1609.34
• Meters/Second to MPH: m/s * 2.237
• Workout Summaries: The /v1/workouts list endpoint returns null for workout_summary. You must call /v1/workouts/ to get specific metrics like NP, TSS, or the FIT file URL.

Error Reference