2026-11-08: The running coach is up
Buenos dias my fellow pandarians! Today, I finally got around to putting together a little project I’ve been thinking of for quite a while.
Some background…
Recently, I have been perusing ye ol’ internet for guidance on my marathon training. And whatever I’d find, I’d notice that it would just not really fit me. Kinda makes sense, people talking about themselves, so, obviiiiii, that does not need to apply to me 100 %. But then what can I do to get proper guidance and advice for my training. I mean, sure, I could pay for a coach, but who on earth has this kind of money in the current economy. I definitely don’t want to spend any of my sweet sweet hard looted (ahem, I mean ‘earned’) bottle caps on that sort of luxury.
Besides, and now I am somewhat tongue-in-cheek: technically speaking, a coach looks at signals and derives individual (and opinionated) advice based on what he sees.
That…sounds like control engineering…with extra steps…? Are sports and fitness coaches isomorphic to PID controllers? I need to think a bit more about this. Anyhow, I digress, back to topic.
Signals and feedback is the name of the game. So then would it not be amazing if I could create this immediate feedback loop of looking at signal (my health metrics) and correcting my training schedules and offer guidance automatically? I know, it could never replace a real coach with real experience, but hey, it is better than nothing, right? RIGHT?
Born out of this was the Run Explorer & Coach at /apps/run-explorer app in the Apps section (check the header for the new button).
The goal of it all
Simple: Give me direct feedback on where I stand with my training, based on my measured health metrics, providing me with the next steps in my training. Instead of guesswork there’s concise and concrete feedback and recommendations based on real numbers.
- My body signals it needs more recovery, the app lets me know that.
- My body is well-rested and needs a good round of torture? Bueno, the app tells me I can up my pace in the following weeks. I tell it where I stand, and where I want to go, it tells me the next few turns.
Kind of like Google Maps, only for my runs. Makes sense, I think.
The thing, more or less, I imagine, targets three of my personalities. It does so via three ways of configuring the app: Simple mode, Expert mode, and ‘IDGAF’.
In Simple mode, I just kinda get the human-friendly feedback on how I’ve been doing around the track / trail / whatever it is I run on or where. It tells me what to do next, what to focus on more, what to do less, as well as a few weeks of training schedule.
In Expert mode, I get way more metrics, as well as a high-level perspective on fitness, fatigue, and more latent things such as efficiency factor and aerobic drift. Here I can get a better overview of how all the weeks leading up to my target will look.
In ‘IDGAF’, I’d go to Expert mode, just check my current fitness and see if if my efficiency (EF) is improving. If the trend coefficient - the slope - is positive, I am doing generally ok, I keep doing what I am doing. Else, I gotta rethink my approach and maybe just use the actual recommendations of Expert mode (duh!).
How it works
It reads my Apple Health export, shows my runs, and builds a training plan for any given race in the future. Below, I outline what it does, how it works, and how I intend to use it.
The whole thing is based around the export.zip that can be generated from Apple Health, which contains all workout data that my Apple Watch records during my runs.
The application is stateless and runs entirely in the browser / in the PWA I run on my iPhone. No health data ever leaves the device. The steps to use it are in Use it from your iPhone below.
The logical flow is the following:
-
Ingest. The worker streams
export.xmlout of the zip. It parses in two passes, because Apple writes Records before Workouts. Only running workouts are kept. That is a technicality and irrelevant to users. -
Store. Runs are cached in IndexedDB in this browser. One entry per workout. A newer import wins.
-
Metrics. Per run: pace, heart rate zones, cadence (from step counts), efficiency factor, aerobic drift and TRIMP. Over time: fitness (CTL, 42 days), fatigue (ATL, 7 days) and form (TSB = CTL minus ATL).
-
Assess. A small set of fixed rules reads the metrics and sets modifiers for the plan:
Rule Trigger Effect Fatigue ATL above 1.5 x CTL Volume x 0.8, next quality session becomes easy Easy runs too hard 2 or more easy-paced runs in 14 days above the easy heart rate cap + 3 bpm Easy pace 10 s/km slower Aerobic drift Median drift of long runs above 5% Hold volume (no ramp) Efficiency Efficiency up 2% or more over 28 days Ramp up to 10% per week instead of 8% No recent runs 0 runs in 7 days Restart from your 4-week average -
Plan. This builds weeks backward from the race date: base, build, peak and taper, with cutback weeks. It is a pure function of goal, fitness, date and modifiers. The same input always gives the same plan.
-
Validate. This enforces the safety limits: a weekly volume cap per distance, at most 2 hard sessions per week, a limit on weekly ramp, and a cap on the long run.
All the formulas
Everything the coach calculates, in one place. The idea is a chain: raw watch samples become a few numbers per run, those numbers become one “cost” per run, the costs add up into fitness and fatigue, and the rules and the plan read those.
samples -> per-run numbers -> TRIMP (cost of a run) -> CTL / ATL / TSB -> rules -> plan
Per run
The watch records a heart rate or speed value every few seconds, not continuously. To get an average over a run, each value is held until the next one arrives and weighted by how long it was held. A gap of more than 30 seconds (a pause, a lost signal) only counts for 30 seconds, so standing at a traffic light does not distort the run.
Pace is how long one kilometre takes, and speed is the inverse view. Lower pace is faster.
Heart rate zones split your effort into five bands by the share of your maximum heart rate, . The bounds are 0.6, 0.7, 0.8 and 0.9. Roughly: zone 1 is recovery, zone 2 is easy aerobic running (the bulk of a good plan), zone 3 is moderate, zone 4 is hard (around threshold) and zone 5 is close to all-out. The coach also uses the top of zone 2 (70 % of max) as the easy heart rate cap.
Cadence is steps per minute. It comes from the step counts of your watch:
Only intervals of 5 seconds to 5 minutes that give 120 to 230 spm count. Anything else is walking or double-counted steps.
Heart rate reserve (HRR) says how hard you are working inside your own range. 0 means resting heart rate, 1 means maximum heart rate:
TRIMP (training impulse, Banister form) turns a whole run into one number: how much it cost your body. Every minute adds points, and the run is the sum of its minutes:
The exponential is the important part: hard minutes count much more than easy minutes. 60 minutes at gives about 100 points. 30 minutes at gives about 98. Half the time at the hard effort costs as much as the full hour at the easy one. Without heart rate samples, the average heart rate of the whole run is used instead.
Efficiency factor (EF) is speed per heartbeat. The higher it is, the less heart it takes to go a given speed, which is what getting fitter looks like. A slowly rising EF over weeks means your aerobic fitness improves.
Aerobic drift compares EF in the first and the second half of the run. In a well-trained aerobic system, heart rate stays flat at constant speed. If it creeps up and EF drops, the base is not solid yet. Above about 5 % is the warning line.
Training load: CTL, ATL and TSB
One run tells you little. What matters is how much you have been doing lately compared to what your body is used to. The coach keeps two running averages of your daily load, where the daily load is the sum of the TRIMP of all runs of that day (0 on a rest day).
Each day, an average moves a fixed fraction of the way towards that day’s load:
- CTL, chronic training load, “fitness”. The slow average (42 days). It is how much training your body has adapted to. It builds slowly with steady training and fades slowly with rest. It halves after about 4 weeks without running.
- ATL, acute training load, “fatigue”. The fast average (7 days). It is how much you did recently. It jumps after a few hard days and is mostly gone after a week of rest. It halves after about 5 days.
The two numbers have no unit. They are points on the TRIMP scale, so they are only comparable with your own numbers, not with another runner’s. Both start at 0 on the day of your first run, so the first weeks of history understate your real fitness.
Example: a single run of 100 points on a day when both are 0 adds to ATL, but only to CTL. Fatigue reacts immediately, fitness barely moves. Only many such days in a row raise CTL.
TSB, training stress balance, “form”, is the difference between the two, taken before the current day is added, so it is your state at the start of the day:
| TSB | Meaning |
|---|---|
| Clearly negative | You did more recently than you are used to. You are tired. Normal in a hard block, risky if it lasts. |
| Around 0 | Steady training. Recent load matches what you have adapted to. |
| Positive | You did less recently than you are used to. You are fresh. This is what a taper aims for before a race. |
This is how the numbers connect to the advice: the coach cuts volume when , which means “the last week was 50 % heavier than your usual load”.
Fitness estimates
To set paces, the coach needs to know how fast you can run. It does not ask you. It estimates it from your hard runs.
Riegel scaling is a well-known rule of thumb: if you can run a time over a distance , you can run about this time over another distance . You slow down a little per kilometre as the distance grows, which is the exponent 1.06:
One lucky run (tailwind, downhill, GPS error) would give a time that is too fast. So the coach scales several runs and takes the median, which ignores one or two outliers. The steps:
- Pool of runs: hard runs in the baseline window (default 90 days). A hard run is at least 15 min long with . If there are none, all runs of 15 min or more are used.
- 10 km prediction: scale every run in the pool to 10 km with Riegel. Take the 5 fastest predictions and use their median, .
- Threshold pace: the pace you can hold for roughly an hour, the border between “hard but sustainable” and “too hard to hold”. It is a bit slower than 10 km race pace:
- Easy HR cap:
- Easy pace: the median pace of runs with easy cap, if there are at least 3. Otherwise .
- Max HR if you do not set it: the 95th percentile of the per-run max heart rate. It is 190 bpm without data.
- Weekly volume: the distance of the last 4 weeks divided by 4.
- Confidence: how far the estimate can be trusted.
highif the pace of the hard runs is at most ,lowif not,noneif the pool is empty.
Race time prediction
The same Riegel idea, from the 10 km estimate to your race distance . The gap compares your target time with the prediction. A negative gap means the target is faster than the prediction.
A target is “ambitious” if the gap is below and “likely out of reach” below . Race-pace work in the plan never goes faster than this:
The rules
The rules look at the numbers above and adjust the plan. None of them is a prediction, they are simple safety and progress checks:
| Rule | Condition | Effect |
|---|---|---|
| Fatigue | Volume x 0.8, next quality session becomes easy | |
| Easy runs too hard | 2 or more easy-paced runs in 14 days with | Easy pace +10 s/km |
| Aerobic drift | Median drift of runs of 60+ min in 28 days above 5 % | Ramp 0 % |
| Efficiency | Median EF of the last 28 days is 2 % or more above the 28 days before (3+ runs in each window) | Ramp 10 % |
| No recent runs | 0 runs in 7 days | Note only |
An easy-paced run has and a pace of at least . The efficiency rule is skipped when another rule already reduced or held the volume.
The plan
A plan is a list of weeks from today until the race week. Terms used below: the ramp is how much the weekly distance grows from one week to the next, a cutback week is a lighter week that lets the body absorb the training, a quality session is the one hard workout of the week (tempo or intervals), and the taper is the reduced training in the last weeks before the race.
Weekly volume, with the ramp (8 % by default, set by the rules) and the number of non-cutback weeks so far:
- Cutback week: every 4th week (week index with ) has .
- Taper weeks: .
- Taper length: 3 weeks for 30 km or more, 2 weeks for 15 km or more, otherwise 1. At most .
- Peak phase: weeks. The weeks before it are split in half into base and build.
- Targets are rounded to 0.5 km.
Split of a week with volume and easy days:
If an easy run would be longer than 75 % of the long run, the long run grows instead, up to its cap:
The most volume the sessions can hold at all:
Paces of the sessions:
- Easy: easy pace plus the modifier. Long: easy pace + 15 s.
- Tempo: thr, or the race pace in peak weeks when there is a target time.
- Intervals: , with repetitions of 1000 m.
Caps by race distance:
| Race distance | Weekly cap | Long run cap |
|---|---|---|
| up to 5 km | 35 km | 12 km |
| up to 10 km | 50 km | 16 km |
| up to 21.1 km | 65 km | 22 km |
| above 21.1 km | 90 km | 32 km |
Plan validation
- Weekly total at most .
- No more sessions than days per week, and no two sessions on one day.
- At most 2 hard sessions (tempo or intervals) per week.
- Longest session at most . The race itself does not count.
- Ramp: a week is rejected only if and . Taper weeks are exempt.
Assumptions
- Apple Health data is the only input. Heart rate, distance and step records are correct.
- Max heart rate is your input. Otherwise it is the 95th percentile of the highest heart rate in each run (190 bpm if there is no data). Resting heart rate is 55 bpm unless you set it.
- Threshold pace is estimated from your recent hard efforts (Riegel scaling, but adjusted because I wanted it to be more robust towards outliers, so it looks at the median of the past 5 runs) unless you set it. Pace targets show a confidence level: high, low or none.
- Cadence is derived from step records and kept only between 120 and 230 steps per minute. iPhone and Watch records can overlap, so cadence is the least reliable metric.
- Days and weeks use UTC, and weeks start on Monday. A run close to midnight can land on the neighbouring day.
- Not yet tested on a very large export (several GB).
Philosophy
- Local first. Health data is private. It stays on your device.
- Rules before AI. This thing is deterministic and swift by design. Every piece of advice comes from a rule you can read, the plan is a pure function, and the rules have unit tests. Expert mode shows the formula and the data behind each recommendation. Simple mode shows the advice and the next 4 weeks.
- Conservative. When fatigue is high or the aerobic base is unstable, the coach reduces or holds load. It does not push.
Use it from your iPhone
- Open the Health app. Tap your profile picture, then Export All Health Data. Wait for the export to finish.
- Save the file to Files (iCloud Drive or On My iPhone). Keep the name
export.zip. If Safari or Files unpacked it, compress the folder again to a zip. - Open thepanda.dev/apps/run-explorer in Safari.
- On Overview & data, tap the file picker, choose
export.zipand wait for the import. Keep the screen on. Large exports take time and memory. - Check Overview and data quality. Look at the Runs tab if you want to see single runs.
- Open Coach. Set race date, distance and days per week. Add a target time if you have one.
- Read the assessment and the plan. Use Export plan or Export PDF to keep it.
Tips:
- Use Add to Home Screen in Safari to open it like an app.
- Want to try it first? Tap Load example runs.
- Import again after new runs. Runs merge by workout id.
- Delete stored runs removes the cached data from the browser.
- Safari can clear site data after a period of no use. Keep your export file for a re-import.
