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

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)

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

Request a visual training plan

Send me this week's training plan as an image

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:

> 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:

| Framework | Application | |-----------|-------------| | Daniels VDOT | Pace zones derived from test results, not guesses | | MAF heart rate | Easy runs at truly easy effort — conversational pace | | FIRST structure | Quality sessions: Interval + Tempo + Long run | | 80/20 polarized | 80% easy volume, 20% quality — prevents overtraining |

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))"

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.