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:

CODEBLOCK0

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:

CODEBLOCK1

Then install the Python library:
CODEBLOCK2

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:

CODEBLOCK3

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

How to use

Log a run (text)

CODEBLOCK4

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.

CODEBLOCK5
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

CODEBLOCK7

Sync Garmin data (optional)

CODEBLOCK8

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:

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

CODEBLOCK9

Agent instructions

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

CODEBLOCK10

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.