Runspector — AI running coach for Garmin

A free, open-source AI running coach for Garmin watches. Runspector syncs your Garmin Connect data - HRV, sleep, Body Battery, resting heart rate, training load and every run - into a file on your own computer, decides each day whether to go hard, keep it easy or rest, and lets Claude explain why and plan your week: in a small local web app, or as a Garmin MCP server in Claude Code and Claude Desktop. No cloud, no API key needed - your own Claude Code sign-in is enough.

https://github.com/user-attachments/assets/0b4d7d86-5ab7-439b-82cb-89a004b71405

_{The 90-second demo, with voice-over: the synthetic demo athlete, rebuilt from this repo by scripts/video.py (file). No player above? The GitHub mobile app shows no videos: ▶ play the demo in the browser.}

_{The built-in synthetic athlete (runspector serve --demo). Every image is regenerated by python scripts/screenshots.py, and the coach card is an unedited agent run against that same demo database, kept in demo-card.json so the picture cannot drift from the app — the decision it explains (EASY, a day after a hard session) is the one on the Today tab beside it. docs/screenshots/ has each of the five tabs full-length, in both themes — e.g. today.png and today-light.png.}

I came to running late, and for a long time my VO2max would not move. I had always trained a lot, and it had never really shown up in that number — so I assumed more of the same would eventually work. It did not. I was training wrong, in ways the watch on my wrist had the data to show me and never did: Garmin collects everything and explains nothing.

That was the idea. The data is already there; let an AI read it and coach — with the training aimed squarely at raising VO2max rather than at collecting kilometres, and with the decision rules written down so the coach explains them instead of improvising. This repository started as that tool for one athlete. It is now installable for anyone with a Garmin watch and Claude Code (a Claude plan is enough).

No cloud backend, no API key needed, no Docker. One Python package that syncs your Garmin data into a SQLite file on your machine, shows it in a small web app, and lets Claude act as your coach — with a deterministic readiness engine underneath, so the AI explains decisions instead of inventing them.

_{If you came for the engineering rather than the running, the five decisions this repository is actually about — each with}

... View full README on GitHub