Velomate：连接 Garmin Connect、用 Gemini 生成自适应骑行训练计划的开源桌面应用

A cycling training dashboard that connects to Garmin Connect and uses Google Gemini to generate personalised, adaptive weekly training plans based on your actual ride data. Ships as a Windows/macOS desktop app with silent background auto-updates.

About this project

Velomate started out as a personal tool to solve a specific problem: I wanted a flexible, adaptive training plan that adjusted to my life. During a period in my life when things were tough and my energy levels were low, I still wanted to keep riding, but I couldn't bring myself to commit to expensive monthly subscriptions like JOIN, TrainerRoad, or Zwift. When you're struggling with energy or when you're just having trouble finding the time, paying a steep monthly fee creates uncomfortable pressure; you constantly worry whether you'll even be able to follow through on the commitment, turning what should be a healthy outlet into an extra burden.

To be fair, commercial platforms back their products with dedicated teams, extensive sports science, and deep professional engineering. But for my day-to-day needs, Velomate proved to work surprisingly well in practice. I strongly believe that incorporating smart AI into an application should be just as seamless, natural, and accessible as having a quick chat with an LLM. AI has become such a fundamental part of our lives, and leveraging adaptive training guidance shouldn't require complex overhead or a recurring monthly paywall.

Yes, this project is roughly 95% "vibecoded" using AI. But it wasn't just built on a whim. It took a clear vision, lots of tweaking and testing to turn it into a reliable, functional application.

It was built with a clear purpose:

Heart Rate-Focused: Train based on true physiological fatigue and internal load, not rigid power numbers.
No Subscriptions & Open Source: Free to use, modify, and self-host forever, a pressure-free alternative to paid cycling apps.
Accessible AI: Powered by Google Gemini's free tier, bringing intelligent training guidance to everyone without monthly fees.
Privacy-First: Your credentials, API keys, and ride data stay strictly on your machine.

To keep development moving quickly and make the app as accessible as possible without the hassle of self-hosting, I packaged it as an Electron desktop app. While I can easily see Velomate working perfectly as a native mobile app, I simply don't have the time and financial resources to build and maintain mobile apps right now.

Whether you run it as a lightweight desktop app or self-host it via Docker on your home server, I hope Velomate makes your training a bit smarter and your rides a bit better, entirely on your own terms.

Feedback, bug reports, and contributions are always welcome!

What it does

Garmin Connect sync — pulls your cycling activities automatically
AI training plans — weekly structured plans generated by Gemini, adapted to your actual load and fatigue
Free training mode — swap the two-week schedule for a single "what should I ride next" suggestion with no fixed day, for when you don't want a calendar at all
Pick your own AI model — choose a free-tier Gemini model from the built-in presets, or enter any model ID Google supports (including paid Pro tiers or ones released after this app was)
HR zone analysis — calculates your personal zones from LTHR/max HR with Garmin data as a starting point
Execution scoring — AI reviews completed workouts and scores them 0–100 based on zone data, RPE and feeling
Week grid — visual overview of planned, completed, skipped and auto-skipped days
Training pause/resume — pause the plan (illness, travel, ...) and auto-pause detection after prolonged inactivity
Garmin workout sync — uploads structured workouts directly to your Garmin device
Self-hosted data — your Garmin/AI credentials and ride history stay in a local SQLite database; nothing is sent anywhere except Garmin and Gemini's own APIs

Your AI coach

Velomate isn't a fixed training program you follow, it's built so the AI acts as an actual coach that adapts to you, not the other way around.

Tell it your goals — goals & preferences fed straight into every plan it generates
Tell it your schedule — set your preferred long-ride days and it shapes the week around them, instead of forcing a generic template on you
It reads your actual training, not a script — every regeneration looks at your recent rides (HR zones, duration, RPE, how you felt afterwards) plus what you did or skipped from the previous plan, and adjusts the coming days from that, not from a static periodization chart
It explains its reasoning — each week's plan comes with a short written rationale for why it's shaped the way it is, not just a list of workouts to blindly follow
It scores how you actually rode — after a workout, the AI compares what you did to what was intended and gives a 0–100 execution score with a one-line explanation, so you get feedback instead of a checkbox
You can push back on it — skip today, reschedule a session, or pause training entirely (illness, travel, burnout) and the AI rebuilds the plan around that rather than rigidly marching on
It notices when you go quiet — after a configurable number of inactive days it pauses training automatically instead of piling up stale, guilt-inducing plans
Or skip the schedule entirely — switch to free training mode and it drops the two-week plan for a single next-workout suggestion you ride whenever suits you, syncing it to Garmin only once you're ready

In short: you set the direction and the boundaries, the AI works out the day-to-day path there, and re-plans every time your real training tells it something new.

Install (desktop app)

This is the easiest and the recommended way to run Velomate.

Go to the Releases page and download the latest installer for your OS:
- Windows — Velomate-Setup-x.y.z.exe
- macOS — Velomate-x.y.z-arm64.dmg (Apple Silicon only — Intel Macs aren't built)
Run the installer.
- Windows note: the installer isn't code-signed yet, so SmartScreen will show an "Windows protected your PC" warning. Click More info → Run anyway.
- macOS note: the app isn't code-signed/notarized yet, so Gatekeeper will block it as "damaged" — right-click the app → Open to bypass this once.
Launch Velomate. On first launch you'll be guided through setup:
1. Connect Garmin — enter your Garmin Connect credentials
2. Add AI API key — generate a 100% free Gemini API key at aistudio.google.com/apikey using any regular Google account (no credit card or subscription required)
3. Confirm training profile — review suggested HR zones from your ride history
4. Generate your first plan — one click

Updates

Velomate checks for updates automatically in the background (every few hours) and downloads them silently. When a new version is ready, a banner appears at the top of the app — click Restart & Install whenever it's convenient. No manual download needed after the first install.

Your data

All data (Garmin activities, AI plans, HR profile, settings) lives in a local SQLite database in your OS user-data folder, it is never touched by an update:

OS	Location
Windows	`%APPDATA%\velomate\velomate.db`
macOS/Linux	`~/.velomate/velomate.db`

Logs live alongside it in a logs/ subfolder there. They are useful for debugging and other insights.

Alternative: self-hosted (Docker)

If you'd rather run Velomate as a headless service on a home server / NAS instead of a desktop app, a Docker setup is included:

git clone https://github.com/t0r3x/Velomate.git
cd Velomate
docker compose up -d

Open http://localhost:2012 and go through the same setup flow as above.

Updating:

git pull
docker compose up -d --build

Your data is preserved — ./data is mounted as a volume and survives rebuilds.

Custom port — edit docker-compose.yml:

ports:
  - "8080:2012"   # access on localhost:8080

Logs — rotate daily, kept for 30 days in ./logs/ by default:

# docker-compose.yml
environment:
  - LOG_DIR=/app/logs
  - LOG_LEVEL=info   # debug / info / warn / error

Backup:

cp -r data/ velomate-backup-$(date +%Y%m%d)/

Without Docker

Install Node.js 20+ (LTS) and run:

npm run install-all   # install dependencies (run once)
npm run build         # build frontend + backend (run once, and after updates)
npm start             # start the server

Open http://localhost:2012. To keep it running in the background on Windows, use NSSM or Windows Task Scheduler pointing to node backend\dist\server.js.

Configuration

Everything is configured through the in-app settings. No environment variables or config files required for the desktop app.

Development

Requires Node.js 20+.

npm run install-all      # install frontend + backend deps
npm run dev               # backend on :2012, frontend on :5173 (browser mode, no Electron)
npm run electron:dev      # same, but launches inside the Electron shell instead of a browser

Building & publishing the desktop app

npm run electron:build    # build installers into dist-electron/, no publish (use to test locally)
npm run electron:publish  # build + upload installers as a GitHub Release (requires GH_TOKEN with `repo` scope)

electron-builder.yml targets GitHub Releases as both the publish destination and the update feed (t0r3x/Velomate). Bump the version in package.json before every publish — that's what both the release tag and electron-updater's version check are based on.

☕ Support the project

If Velomate helps you train smarter on your own terms and you'd like to support its ongoing development (or buy me a coffee for the late-night prompt engineering), any support is deeply appreciated!

License

MIT