Documentation

OpenPacemaker user guide.

Everything you need to get set up, understand what the bot can do, and get the most out of it day to day.

Getting Started

OpenPacemaker lives entirely in Telegram. There's no app to download and no dashboard to learn — connect your Strava account once, run through a short setup, and the bot has everything it needs.

Connect Strava

Click your invite link — it opens @runwhisperer_bot directly in Telegram. The bot sends you an authorisation link. Click it, approve read-only access on Strava, and you're connected.

Read-only access only. OpenPacemaker can read your activities, profile, and heart rate data. It cannot create, modify, or delete anything on Strava.

Initial setup (~5 minutes)

Run through these four steps once after connecting Strava. Each one unlocks more of the coaching experience.

Sync your activity history — /sync Pulls up to 12 months of activities into the database so the coach has context from day one, not just runs from today onwards.

Set your HR zones — /setzones <resting> <max> Zones are used to classify effort in every run and to compute training load (CTL/ATL/TSB). Without them, /breakdown, /load, and /analyse work in limited mode.
Example: /setzones 48 188

Run your athlete assessment — /onboarding The coach analyses your full history, asks about injuries and preferences, then generates a personalised training plan. Takes about 5 minutes and only needs to be done once.

Add your personal bests — /setpbs If you have PBs from before your Strava history, tell the bot: /setpbs 5K in 17:30, 10K in 37:40, half marathon in 1:21. These feed into VDOT calculations and pace zone recommendations.

Write descriptive Strava titles

The coach reads your Strava activity title and description to understand the intent behind each session. "Easy 10k, kept it conversational" tells a very different story than "10.0 km".

Good examples:

Easy recovery jog — legs still heavy from Sunday
Tempo 3×2km @ HM pace, felt strong
Long run 26km — bonked at 22, nutrition off

Commands

All commands available in the Telegram bot, grouped by function. Most commands also have a short alias — e.g. /analyse and /reanalyse do the same thing.

Getting started

/start

Show your status overview, sync state, and a link to connect Strava if not yet linked.

/sync

Fetch your latest activities from Strava. Run this if the bot seems out of date.

/onboarding · /setup

Guided athlete assessment — analyses your full Strava history, asks about injuries and preferences, then generates a personalised training plan automatically. Run once after connecting Strava.

/login

Reconnect your Strava account if your authorisation has expired.

Daily coaching

/today

Today's prescribed training session from your plan — type, target pace, distance, and notes. Shows ✅ if already completed.

/week [N]

This week's actual km vs planned km with a day-by-day breakdown. Pass a week number to see a specific week.

/week 3

/review

Weekly coach review on demand — week summary plus a Claude-generated coaching narrative with a forward-looking suggestion for next week. No day-of-week restriction; safe to run any time, including after a Sunday long run.

/countdown

Days remaining to your goal race, current training phase, and a one-line readiness note.

/last

Full detail on your most recent activity: distance, pace, HR zones, GAP, and how it compared to the plan.

/plan · /planview

Week-by-week training plan overview showing each week's sessions and total planned km.

Analysis

/analyse · /reanalyse

Claude analyses your last activity against the training plan — effort flags, HR zone distribution, coaching verdict, and debrief prompt.

/load

Training load dashboard: CTL (fitness), ATL (fatigue), TSB (form) from your actual Strava data, with a 12-week chart.

/score · /myscore

This week's training compliance score. Each session rated 0–100 on intensity and distance vs plan. Shown as a traffic light — 🟢 ≥80% · 🟡 60–79% · 🔴 <60% — with a 4-week trend.

/race · /readiness

Race readiness assessment based on CTL, TSB, plan adherence, and recent training quality.

/breakdown [weeks]

Time-in-zone breakdown across the last N weeks, calculated from second-by-second Strava heart rate streams — not lap averages.

/breakdown 6

/adherence [weeks]

Plan adherence score: sessions completed, partial, missed, and rest days honoured over the last N weeks.

/adherence 8

Training plan

/setplan <goal>

Generate a new personalised training plan. Describe your goal race, current fitness, and constraints in plain English. The more detail you give, the better the plan — see the prompt guide below.

/setplan half marathon 1:21 May 17th, max 5 days, Tue/Fri/Sun, max 70km/week, currently running 60km/week in ~1:28 shape

/edit · /editweek <N> <instruction>

Ask Claude to adapt a specific week — swap sessions, reduce load, or add a race.

/edit 4 I have a work trip Wednesday–Friday, adjust accordingly

/reschedule <session>

Move a specific session to a different day in the same week.

/recover · /easyweek

Dial back the current week — reduces volume and intensity for recovery.

Zones & results

/setzones <resting> <max>

Recalculate HR zones using the Karvonen formula from your resting and max heart rate.

/setzones 48 188

/zones

Show your current HR and pace training zones.

/pbs · /setpbs <results>

Save personal bests in plain English. Feeds VDOT calculations and pace zone recommendations.

/setpbs 5K in 17:30, 10K in 37:40, half marathon in 1:21

/results

Race results log with VDOT equivalents and predictions across distances.

Health & wellness

/wellness · /health

Show your active injury and wellness log.

/wellness <body_part> <1–10> [notes]

Log a new issue. Severity 1 = minor niggle, 10 = can't run. The coach tracks these and factors them into load recommendations.

/wellness left knee 4 tight after long run

/wellness resolve <id>

Mark an issue as resolved.

/memory

Show coaching memory stats — notes the bot has stored about your training history and preferences.

Garmin integration

/garmin connect

Link your Garmin Connect account. Authenticates via Garmin SSO (including 2FA). Only needs to be done once per year.

/garmin [week]

Upload the current week's sessions directly to Garmin Connect as structured workouts with VDOT-based pace targets. Pass a week number to upload a specific week.

/garmin 6

Settings & account

/preferences

Adjust training volume, session difficulty, and your daily morning check-in time. Changes take effect immediately.

/style [direct|supportive|minimal]

Set the coaching tone. Direct is the default — honest, no filler. Supportive adds more encouragement. Minimal keeps responses very short.

/filter · /sport [type]

Filter by sport: run / ride / hike / swim / all. All analysis focuses on this type.

/model [haiku|sonnet|opus]

Switch the Claude model for chat responses. Haiku is fastest, Opus is most capable.

/data · /mydata

View a summary of all data stored for your account — activities, memories, plan, settings, and more.

/export

Download all your data as a JSON file.

/exportcal

Download your training plan as an .ics calendar file — import into Google Calendar, Apple Calendar, or Outlook.

/feedback <message>

Send feedback directly to the developer — bugs, ideas, anything.

/feedback the RPE buttons are great but I'd love a Monday morning weekly summary

/clear

Clear the current conversation history. Useful if the context gets cluttered.

/delete confirm

Permanently and immediately delete all your data from OpenPacemaker. This cannot be undone.

Coach features

/coachlink · /coach <coach_code>

Link yourself to a coach. Ask your coach for their code (their Telegram user ID) and run /coachlink <code>. Running it with no argument shows usage.

/roster · /myroster

Coaches: view your linked athletes with recent activity summaries. Also shows your coach code to share with athletes.

Day-to-day use

Once configured, the bot fits into your routine naturally. Here's what a typical week looks like.

Morning check-in

Each morning the bot sends a personalised briefing — today's session, current phase, and any flags from recent training. You can also pull it on demand:

/today

Today — Week 6, Day 1
Easy aerobic run · 10 km · Z2 HR
Keep pace conversational. Focus on time on feet, not speed.

Post-run analysis

Activities sync automatically when you finish a run on Strava. The bot analyses it against the plan and asks for your effort rating. You can also trigger analysis manually:

/analyse

Tempo 8km — Analysis
Avg HR 168 bpm (Z4) · 4:12/km avg
✅ Effort matched plan · 72% in target zone
⚠ Last 2km drifted to Z5 — consider 2×4km next week.
How did it feel? Rate effort 1–10.

Ask in plain English

You don't need commands for everything. Ask the coach anything directly:

My left knee has been sore after runs, should I be worried?

Based on your recent load (TSB -14, ATL rising), this might be early overreach. Your easy run Tuesday had avg HR 158 — that's Z3, not recovery pace.

Swap Thursday's session for a true Z1 jog or rest. Want me to adjust the plan? Also log this with /wellness left knee 3 so I can track it.

Weekly debrief

On Sunday evenings the bot sends a weekly summary automatically. You can also pull it any time:

/week

Week 6 vs Plan
Planned 52 km · Actual 47 km (90%)
Mon ✅ Tue ✅ Wed ⏭ skipped · Thu ✅ Fri – · Sat ✅
Good week overall. Skipped Wednesday — planned rest next week.

Tips

Write Strava titles like a training diary. The more context you give — effort, niggles, conditions — the better the coaching analysis.

Answer RPE prompts after hard sessions. When the bot asks for an effort rating, answer it. This feeds the coaching memory and improves future plans.

Log niggles early. Use /wellness <body_part> <1–10> as soon as something feels off. The coach tracks these and factors them into load recommendations.

Ask follow-up questions. After /analyse, the conversation is open — "should I change next week?" or "what pace should I target for the race?" are both fair game.

Use /preferences to tune the plan. You can adjust training volume, session difficulty, and the time of your daily morning check-in without regenerating the whole plan.

Ask in plain English. You don't need to remember every command. "How does my training load look this week?" works just as well as /load.

Data & privacy

What's stored

OpenPacemaker stores the following data for each user: Strava activities (distance, pace, HR, elevation), training plan, post-run RPE debriefs, wellness log, coaching memory notes, conversation history, and account settings. Nothing else.

Exporting your data

Send /export to download everything as a JSON file. Send /exportcal to download your training plan as an .ics calendar file you can import anywhere.

Deleting your data

Send /delete confirm to permanently and immediately delete all your data. This cannot be undone. You can also revoke Strava access from your Strava settings at any time.

Strava access

OpenPacemaker requests read-only Strava access. It can never post, create, or modify activities on your behalf. You can revoke access at any time from your Strava app settings.

Writing a great `/setplan` prompt

The plan generator is Claude under the hood — it responds well to natural language and uses everything you tell it. A richer prompt produces a much better plan. Here's what to include:

The essentials

Race + date + target time. Be specific: event name, full date, goal finish time. "Hackney Half on May 17 2026, target 1:21" is better than "half marathon in spring".
Current shape. Your best recent estimate — a recent race time, a recent long run pace, or just a rough equivalent. "Currently in 1:28 shape" or "ran 10k in 44 mins last month".
Weekly volume. How many km/week you're already running, and how many you want to cap at. "Running 60km/week now, happy to stay at 60–70km".
Days and sessions per week. Maximum number of days, and which days if you have a preference. "Max 5 days, sessions on Tuesdays and Fridays plus a long run Sunday".

Things that improve the plan significantly

Personal bests. Your all-time PBs anchor the VDOT model and pace zones. "PB is 1:23:47 half".
Terrain. What you have access to — hills, flat loops, track. The coach will assign hill reps and track sessions when appropriate. "I have hills, a track, and flat park loops".
Cross-training. If you cycle, swim, or do gym work, mention it and roughly how often. It factors into the overall load picture.
VO2max estimate. Garmin or Apple Watch often gives this. "Garmin shows VO2max 56". Helps calibrate intensity targets.
Start date and any immediate sessions. You can ask for the plan to start from a specific date and include sessions you want in the first day or two. "Start from yesterday, include a 4×2km tempo today".

What you don't need to specify

Your full Strava history is already loaded — the coach can see your recent training, longest runs, HR zones, and load trend. You don't need to summarise your training history; just describe what you want.

Example prompt

/setplan

race Hackney Half on May 17 2026 · target 1:21

schedule 5 sessions a week max · Tuesdays and Fridays plus a long run Sunday

fitness currently in 1:28 shape · PB 1:23:47

volume already running 60km/week · stay at 60–70km, no need to build up

terrain hills (Hampstead Heath) · athletic track · flat park loops

cross-training easy bike ride once a week

vo2max 56

start from yesterday · include a 4×2km tempo today

Editing the plan after generation

You don't need to get everything right first time. Once the plan is generated, you can:

Edit a week with /editweek <N> <instruction> — e.g. "remove the track session in week 3, I'm travelling"
Move a session with /reschedule <session>
Dial back a week with /recover if you're tired or ill
Ask in plain English — "can you swap Thursday and Saturday this week?" works fine