Runspector — AI running coach for Garmin

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 the measurement behind it — are in Design decisions. The short version: the verdict is pure code and only the *explanation* is AI · the agent runs on an allowlist, not a denylist (--tools "", one MCP server, empty temp cwd) · prompts are regression-tested by an LLM-as-judge suite whose last run is in the repo · quantities that exist in two languages are pinned by executing the shipped JavaScript against the Python · and the release gate scans binaries too, with a false-positive counter-case. CI runs lint, 1674 tests, 151 frontend tests and that gate on three operating systems and two Python versions, with every action pinned to a commit SHA — and a second job that builds the wheel, installs it as a user would and drives the installed executable through this quick start on all three systems, because the suite proves the code and only an install proves the package.

Formerly runcoach-ai : same project, renamed in v0.5.0. Old links redirect here. Coming from it: three steps to switch over , and your data moves by itself.

Not affiliated with Garmin. Uses the unofficial

python-garminconnect library against your own account.

This is a training tool, not medical advice.

Quick start

# 1. install (needs uv: https://docs.astral.sh/uv/)

uv tool install runspector

without uv: pipx install runspector

2. look around without any account

runspector serve --demo

3. the real thing

runspector serve # first start: checks Garmin and Claude, opens http://127.0.0.1:8765 -

sign in to Garmin right there (Setup → Sign in to Garmin; only a

session token is stored) - and syncs the last 30 days in the background

Garmin is signed into on the page itself (Setup → *Sign in to Garmin*, or *Sign in again* when the session has expired): e-mail, password and Garmin's code if your account uses one, and the sync starts right after. runspector login does the same from any terminal, and a running app picks it up on ↻ - no restart. Claude is only needed for the coach cards: see Connecting Claude.

runspector doctor tells you what is missing — it checks the Garmin session by actually using it, and reports the data age, because a token that quietly expired is how this kind of app dies. Use runspector doctor --offline to skip the Garmin call. Exit 1 means something needs fixing, so runspector doctor || notify-me works in a cron; a missing Claude CLI is reported but does not set it, since everything except the coach cards works without it.

Garmin MCP server for Claude Code and Claude Desktop

The same data, and the same rules, as an MCP server with 18 tools - among them today's readiness verdict, recovery, training load, recent runs, intensity distribution, the VO2max history, what the coach has learned about you, a Garmin sync, a check-in when you say you are ill or hurt - and propose, change, apply and undo for the workouts on your watch.

claude mcp add runspector -- runspector mcp

then just ask: "should I train today?"

or: "plan me an easy 40 minutes for tomorrow" - you see the session, and it goes

on your watch only after you say yes ("take it back off" undoes it)

In Claude Desktop, or any MCP client with a JSON configuration (sign in once first: runspector login):

{ "mcpServers": { "runspector": { "command": "uvx", "args": ["runspector", "mcp"] } } }

Keep it fresh without the app (cron / Task Scheduler): runspector sync. For the morning: runspector today --sync prints today's call in a few lines - GO / EASY / REST with its sentence, the signals behind it, today's planned session with its easier option - and exits 3 when there is nothing from today yet, so a cron and any notifier can tell "not synced" from "rest day".

Later on:

uv tool upgrade runspector     # the newest release; your data and Garmin session stay where they are

uv tool uninstall runspector # removes the program only - delete ~/.runspector yourself if you want the data gone

uv tool install runspector takes the latest release from PyPI (runspector==0.10.0 pins one; pipx install runspector and pipx upgrade runspector do the same without uv); uv tool install git+https://github.com/edxleon/runspector takes whatever is on main.

Connecting Claude

runspector does not connect to Claude itself and never asks for a Claude password or key. The coach runs on Claude software you sign into with your own account, through Anthropic's own sign-in.

What "a Claude plan" means. Claude Code needs a paid Claude subscription from claude.com/pricing - Pro, Max, Team or Enterprise - or an Anthropic Console (API) account, which is billed per use. The free Claude plan does not include Claude Code. On a plan, the coach cards count against that plan's usage like any other Claude Code use: there is no key to create and no bill per card. runspector itself is free.

With Claude Code (needed for the coach cards)

Claude Code is Anthropic's command-line tool. You only install it and sign in once; runspector starts it in the background for each card.

# 1. install - macOS / Linux (Windows PowerShell: irm https://claude.ai/install.ps1 | iex)

curl -fsSL https://claude.ai/install.sh | bash # or: brew install --cask claude-code

2. sign in - opens your browser, sign in with your Claude account

claude auth login

3. check

runspector doctor # "Claude: signed in with your Claude subscription"

More install options (WinGet, npm, Linux packages): Claude Code setup. If Claude Code was missing when you started runspector serve, reload the page afterwards - no restart.

If your Claude Code is signed in with a Console API key or a cloud provider (Bedrock, Vertex) instead of a plan, the cards run on that and are billed there; the setup check says so. An ANTHROPIC_API_KEY that is only exported in your shell, for other work, is removed from the card runs unless you set RUNSPECTOR_ALLOW_API_KEY=1.

With Claude Desktop only (no command-line tool for Claude)

If you use the Claude desktop app (claude.ai/download), you can coach in its chat without Claude Code:

1. Install runspector and sign in to Garmin once (runspector login, or the page of runspector serve).
2. In Claude Desktop: the Claude menu → Settings… → Developer → Edit Config, and add:

   { "mcpServers": { "runspector": { "command": "runspector", "args": ["mcp"] } } }

(the file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows; keep any servers already in it).

1. Quit and restart Claude Desktop, then ask: *"should I train today?"*

If the server does not show up, Claude Desktop may not find the command: put the full path from which runspector (Windows: where runspector) into "command". The web app's coach cards still need Claude Code; in Desktop the same coaching happens in the chat.

Without Claude

The readiness verdict and its reasons, the ru