Strava Training Coach

AI running coach that prevents injuries by monitoring your Strava training load daily. Detects dangerous mileage spikes, intensity imbalances, and recovery g...

Evidence-based AI training partner that catches injury risk before you feel it.

Why This Matters

Most running injuries follow the same pattern: too much, too soon. Nielsen et al. (2014) found that runners who increase weekly distance by more than 30% have significantly higher injury rates. By the time you feel pain, the damage is weeks old.

This coach watches your Strava data daily and alerts you before problems become injuries — so you stay consistent instead of sidelined.

Built on the 80/20 polarized training model (Seiler, 2010; Stoggl & Sperlich, 2014) — the same approach used by elite endurance coaches to build durable athletes who train smarter, not just harder.

What You Get

• ACWR Monitoring — Tracks your acute:chronic workload ratio (Gabbett, 2016). ACWR > 1.5 = high injury risk
• Acute Load Alerts — Weekly mileage up 30%+? You'll know before your knees do
• 80/20 Intensity Checks — Too many hard days eroding recovery? Get evidence-based recommendations
• Recovery Nudges — Extended gaps that might affect your training adaptations
• Weekly Reports — Sunday summaries with 4-week trends, ACWR, and intensity distribution
• Oura Integration — Optional sleep/readiness scores to inform training decisions

Quick Start

1. Connect Strava

# Set your Strava API credentials (required)
export STRAVA_CLIENT_ID=your_id
export STRAVA_CLIENT_SECRET=your_secret

# Authenticate (opens browser for OAuth)
python3 scripts/auth.py

Tokens are stored in ~/.config/strava-training-coach/strava_tokens.json with 0600 permissions.

2. Set Up Notifications (Required)

Discord:

export DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
export NOTIFICATION_CHANNEL=discord

Slack:

export SLACK_WEBHOOK_URL=https://hooks.slack.com/...
export NOTIFICATION_CHANNEL=slack

⚠️ Security: Webhook URLs must be set via environment variables. No hardcoded URLs allowed.

3. Optional: Enable Oura Integration

export OURA_ENABLED=true

Requires Oura CLI authentication.

4. Run

# Daily training check + alerts
python3 scripts/coach_check.py

# Weekly summary report  
python3 scripts/weekly_report.py

Optional: schedule with cron for hands-off monitoring:

{
  "name": "Training Coach - Daily Check",
  "schedule": {"kind": "every", "everyMs": 86400000},
  "command": "python3 scripts/coach_check.py"
}

Security Features

This skill is designed with security in mind for ClawHub publication:

Credential Handling

• No hardcoded secrets — All credentials via environment variables
• Secure token storage — Tokens saved with 0600 permissions
• XDG compliance — Config stored in ~/.config/strava-training-coach/
• Token validation — Structure validation before use

Input Validation

• Date format validation — ISO8601 format checking
• Numeric range validation — All thresholds bounded
• Type checking — Safe type conversion with defaults
• Webhook URL validation — Pattern matching for Discord/Slack

Data Protection

• Log redaction — Sensitive data masked in logs
• Secure temp files — Proper permissions on state files
• No data leakage — Safe error messages
• Rate limiting — Max 1 alert per hour per type

Network Security

• HTTPS only — All API calls use TLS
• Timeout handling — 30-second timeouts on all requests
• Retry logic — 3 attempts with exponential backoff
• Certificate validation — Standard SSL verification

Configuration

All thresholds are optional — sensible defaults with validation.

# Training thresholds (validated ranges)
MAX_WEEKLY_MILEAGE_JUMP=30     # 5-100%, default: 30
MAX_HARD_DAY_PERCENTAGE=25     # 5-100%, default: 25
MIN_EASY_RUN_HEART_RATE=145    # 100-200 bpm, default: 145

# Feature flags
OURA_ENABLED=false             # Enable Oura integration
VERBOSE=false                  # Enable debug logging

Example Alerts

Injury Risk

"Weekly mileage up 45% (18 -> 26 mi). ACWR: 1.62. Nielsen et al. (2014) found >30% weekly increases significantly raise injury risk. Your acute:chronic workload ratio is in the high-risk zone (>1.5). Reduce next week's volume by 20-30%."

"60% of runs were moderate/high effort (HR >145). Seiler (2010) found elite athletes keep ~80% of sessions below VT1. Polarized training produces better VO2max gains than moderate-intensity training (Stoggl & Sperlich, 2014)."

"5 days since last activity. Mujika & Padilla (2000) found VO2max begins declining after ~10 days of inactivity. A gentle 20-min walk or easy jog can maintain adaptations."

Achievements

"30-Day Streak! Consistency beats intensity. Holloszy & Coyle (1984) showed mitochondrial density increases with repeated aerobic stimulus."

Weekly Reports (Sunday)

• Weekly mileage with week-over-week change %
• Acute:Chronic Workload Ratio (ACWR) with risk zone
• Intensity distribution (easy/moderate/hard) vs. 80/20 target
• 4-week trend visualization
• Evidence-based recommendations for next week

Training Philosophy (Evidence-Based)

1. Polarized Training — 80% easy, 20% hard (Seiler & Kjerland, 2006; Stoggl & Sperlich, 2014)
2. ACWR Sweet Spot — Keep acute:chronic workload ratio between 0.8-1.3 (Gabbett, 2016)
3. Progressive Overload — Gradual increases; >30% weekly spikes raise injury risk (Nielsen et al., 2014)
4. Consistency > Intensity — Frequency drives mitochondrial and capillary adaptation (Holloszy & Coyle, 1984)
5. Strength Training — Reduces sports injuries by 68% and overuse injuries by ~50% (Lauersen et al., 2014)

See references/training-principles.md for the full guide with 30+ scientific references.

Files

• scripts/auth.py — Strava OAuth setup (tokens stored in XDG config dir)
• scripts/coach_check.py — Daily training analysis and alerts (security-hardened)
• scripts/weekly_report.py — Sunday summary reports (security-hardened)
• references/training-principles.md — Evidence-based injury prevention guide

Smart, Not Spammy

Alerts fire only when something matters:

• Mileage spike detected
• Intensity pattern concerning
• Meaningful PR achieved
• Weekly summary ready

Not every workout. That's what Strava is for.

Rate Limits

• 1-2 API calls per check
• Strava allows 100 req/15 min, 1000/day
• Daily checks use ~30 requests/month