run-coach

Run Coach 🏃

A science-based running coach that works through Telegram. Logs your training, sends visual training plans as HD photo albums, syncs Garmin data, and coaches you with data-driven feedback.

Works for any runner — whether you're jogging 3x a week for fitness or training for your first marathon.

What it does

• Training log — Record every run: distance, pace, heart rate, feel score
• Visual plans — Training plans rendered as HD images sent to your Telegram Photos tab
• Trend tracking — Pace, heart rate, mileage trends over weeks and months
• Garmin sync — Pull data automatically from Garmin Connect (optional)
• Injury monitoring — Tracks knee, plantar fascia, IT band signals
• 4-week reviews — Automatic progress analysis every 4 weeks
• Race prep — Structured build-up for 5K, 10K, half marathon, or full marathon

Setup

1. Required environment variables

Set these in your OpenClaw config or .env:

TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM_CHAT_ID=your_telegram_user_id

To get your TELEGRAM_CHAT_ID: send /start to your bot — it will show Your Telegram user id: XXXXXXXXXX.

2. Fill in your profile

Edit MEMORY.md with your personal data: age, running history, injuries, goal race.

3. Optional: Garmin integration

⚠️ Known limitation: Garmin periodically changes their login flow. The garminconnect library may stop working after a Garmin-side update until the library maintainers patch it. Check garminconnect releases if sync suddenly fails. The rest of the bot works fine without Garmin — you can always log runs manually.

⚖️ Legal note: garminconnect uses Garmin's unofficial API (no official API exists). This may technically conflict with Garmin's Terms of Service. It accesses only your own data and Garmin has not acted against individual users, but use at your own discretion.

Set these additional env vars for automatic Garmin Connect sync:

GARMIN_EMAIL=your_garmin_email
GARMIN_PASSWORD=your_garmin_password

Then install the Python library:

pip install garminconnect

4. Optional: Visual training plans (self-hosted)

The image pipeline (visual training plans sent as Telegram photos) requires additional system dependencies. Install these in your container/environment:

# CJK fonts + emoji
apt-get install -y fonts-noto-cjk fonts-noto-color-emoji
fc-cache -f

# Playwright Chromium (chrome-headless-shell)
npx playwright install chromium

Without these, the coaching features still work — plans will be sent as text instead of images.

How to use

Log a run (text)

I ran 8km today, pace 5:30/km, avg HR 135, felt good

Log a run (screenshot — no Garmin needed)

Take a screenshot of your watch, running app (Strava, Nike Run Club, Apple Watch, etc.), or any device that shows your run data, and send it directly to the bot. The bot's built-in vision capability (LLM multimodal input) extracts the numbers — no OCR code is included in this skill.

[send screenshot of your watch/app summary]
Please log this run and give me feedback

Works with any device — the LLM reads the image natively, no integration required.

Request a visual training plan

Send me this week's training plan as an image

The bot calls training/text-to-image.sh and sends the plan as a Telegram photo album — appears in your Photos tab, full quality.

Get a weekly summary

Summarize my training this week

Sync Garmin data (optional)

Sync my Garmin data and give me feedback on today's run

Image pipeline

Training plans are rendered using Playwright + chrome-headless-shell and sent via Telegram sendMediaGroup (photo album). This means:

• ✅ Appears in Telegram Photos tab
• ✅ No compression on text
• ✅ CJK (Chinese/Japanese/Korean) and emoji supported
• ✅ Weekly plans sent as 2-photo album: run days + cross-training days

Note: The image pipeline requires Telegram. If you use a different channel (Discord, WhatsApp), the coaching features still work — only the visual plan sending is Telegram-specific.

Training methodology

Based on three evidence-based frameworks:

Safety rule: pain >4/10 means stop. Always.

Files included

run-coach/
├── SKILL.md              # This file — manifest + instructions
├── MEMORY.md             # User profile template (fill in your data)
├── training/
│   ├── send-plan.sh      # HTML → screenshot → Telegram album
│   ├── text-to-image.sh  # Text → HTML → screenshot → Telegram album
│   ├── screenshot.mjs    # Playwright screenshot engine
│   └── send-album.mjs    # Telegram sendPhoto (single) or sendMediaGroup (multi)
└── garmin/               # Optional Garmin integration
    ├── garmin-sync.py
    └── garmin-query.py

Agent instructions

When the user asks to send content as an image, use exec to run:

# Option A: convert text to image
bash training/text-to-image.sh "Title" "Content with \n line breaks"

# Option B: weekly plan as 2-photo album (run days + cross-training days)
bash training/send-plan.sh "Week X Plan" training/week-XX-run.html training/week-XX-cross.html

# Option C: single HTML (today's plan, summaries — not for weekly plans)
bash training/send-plan.sh "Title" training/week-XX.html

Do NOT use canvas, browser, or Playwright directly. Only these two scripts.

If a script errors, report the exact error to the user — do not silently switch to text.

For all numeric calculations (pace conversions, HR zones, VDOT), use exec:

node -e "console.log(42.195 / (3*60+55))"

Never calculate in your head.