Pacer — Home Assistant Add-on

Fork. Built on ha-garmin-fitness-coach-addon and ha-garmin-fitness-coach-app by Anil Belur (Apache-2.0 / MIT), which in turn build on create-t3-turbo (MIT). Renamed to Pacer and maintained as a standalone, self-hosted add-on. Attribution and the statement of changes required by Apache-2.0 §4(b) are in NOTICE; the changes themselves are listed in pacer/CHANGELOG.md.

AI-powered sport scientist that turns your Garmin data into actionable coaching, training analysis, and recovery optimization — running entirely on your local network.

• Features
• Architecture
• Installation
• Configuration
• Garmin Authentication
• AI Backend Options
• Automation Blueprints & Templates
• Garmin Watch Compatibility
• Troubleshooting
• Development
• Contributing
• Disclaimer
• License

• 🏋️ Training Load Analysis — CTL / ATL / TSB (Banister fitness-fatigue model), ACWR injury-risk tracking (Hulin 2016)
• 📊 Zone Analytics — HR zone distribution, Seiler polarization index, efficiency trends, calendar heatmap
• 🧠 AI Specialist Agents — Sport scientist, psychologist, nutritionist, recovery coach (via HA Conversation, local Ollama, or rules-based)
• 🏃 Race Predictions — Riegel formula for 5K / 10K / half-marathon / marathon
• 💤 Sleep Coaching — Sleep debt tracking, bedtime recommendations, quality trends, stage analysis
• 📈 6+ Year Trends — Long-term multi-metric overlay charts with rolling averages and notable-change detection
• 🩺 Readiness Score — Evidence-based daily score (0-100) using HRV, sleep, training load, and stress (Buchheit 2014)
• 🚨 Stress Board — Scores calendar meetings against your heart rate (90-min local baseline, ridge regression over attendees) to rank which people spike — or calm — your HR; links Google Calendar and merges HA-logged out-of-calendar interactions
• 🔒 Fully Private — All data stays local; AI runs on your hardware

Pacer runs as a single s6-overlay service (pacer) inside the add-on container. On boot it waits for PostgreSQL, pushes the Drizzle schema, then starts the web app and several background loops. Startup order: postgresql → garmin-auth (parallel) → pacer → sync → metrics → notify → Next.js (:3001) → ingress proxy (:3000) → monitoring loop.

The Garmin and Strava credentials are given only to the Python workers and the auth server — neither the web app nor the internet-facing proxy inherits them. The ingress proxy is the only process reachable from the hassio network and carries no secrets beyond its own per-boot token.

Supported architectures: amd64, aarch64.

Pacer is installed as a local add-on: Home Assistant builds the image on your own machine from this repository. There is no prebuilt image and no public add-on store entry.

1. Copy the pacer/ folder of this repository to /addons/pacer/ on your Home Assistant host. HA expects config.json to sit directly beneath the add-on folder, so copy pacer/, not the repository root. Over SSH:

   rsync -a --delete pacer/ root@<haos-host>:/addons/pacer/

   The Samba or "Advanced SSH & Web Terminal" add-ons both expose /addons.
2. In Home Assistant go to Settings → Add-ons → Add-on Store → ⋮ → Check for updates. Pacer appears under Local add-ons.
3. Click Install. The first build takes roughly 5 minutes on amd64 and 10-15 minutes on aarch64, since the Next.js app is compiled from source.
4. Start the add-on — it appears in your sidebar automatically.

To update, re-copy the folder and rebuild from the same screen.

1. Open the addon from your HA sidebar (or Settings → Add-ons → Pacer → Open Web UI).
2. Complete the onboarding wizard (4 steps):
   • About You — age, sex, weight, height
   • Your Sports — select sports and goals for each
   • Weekly Schedule — training days and session duration
   • Health & Safety (optional) — health conditions, injuries, medications
3. Connect Garmin — go to Settings → Connect Garmin, enter your email and password. If MFA is enabled, enter the verification code when prompted.
4. Wait for initial sync — the first sync pulls your full Garmin history (up to 6+ years). This takes 30-45 minutes due to Garmin API rate limits. You can monitor progress in Settings (a progress bar shows sync status). Subsequent syncs only pull the last 7 days and take ~30 seconds.
5. Restart the addon after the first sync completes to trigger the metrics compute and HA sensor push.

💡 Tip: You can trigger a manual sync at any time from Settings → 🔄 Sync Now without waiting for the next scheduled interval.

Pacer authenticates with Garmin Connect using a web-based auth flow:

1. Open the addon Web UI (sidebar → Pacer).
2. Navigate to Settings → Connect Garmin.
3. Enter your email and password. If your account has MFA enabled you will be prompted for the one-time code during the same flow.
4. On success the addon stores an OAuth session token locally in /data/garmin-tokens/. No credentials are sent to any third-party service.

Token lifetime: The session token is valid for roughly one year before Garmin forces a re-authentication. The addon will surface a notification when a token refresh is needed.

ha-notify.py pushes a set of Home Assistant sensors via the Supervisor API, including:

Six ready-to-import Home Assistant blueprints are included in pacer/rootfs/app/blueprints/. Import them via Settings → Automations → Blueprints → Import Blueprint using the raw GitHub URL:

All blueprints use configurable inputs (thresholds, notification targets, scenes) with sensible defaults for Pacer sensor entities. Seven further ready-to-paste automations (voice ACWR query, sleep-debt management, and more) live in HA_AUTOMATIONS.md.

The engine unit tests cover the deterministic maths — readiness, strain, ACWR, CTL/ATL/TSB, VO2max, forecasting and the daily recommendation rules:

cd pacer/app && pnpm --filter @acme/engine test

These matter because readiness scoring and workout recommendation are implemented twice — in Python for the Home Assistant sensors and in TypeScript for the web UI — and the accuracy-reference spec is what keeps the two in agreement.

Pacer connects to the Garmin Connect web API — not directly to your watch. Any Garmin watch that syncs to Garmin Connect will work, but the depth of coaching features depends on which sensors your watch has.

Watches with Body Battery, HRV, VO2 Max, and Training Status:

• Forerunner 165, 255, 265, 955, 965
• Fenix 7, 7X, 8, 8X
• Epix (Gen 2), Epix Pro
• Enduro 2, 3
• MARQ (Gen 2)

All metrics available: training load (CTL/ATL/TSB), ACWR injury-risk, HR zone polarization, recovery scores, sleep staging, Body Battery trends, HRV status.

Watches with HR + sleep but limited/no Body Battery or HRV:

• Vivoactive 4, 5
• Venu 2, 2 Plus, 3, Sq, Sq 2
• Instinct 2, 2X, Crossover, Solar

Most coaching works. Body Battery and HRV-based recovery may show as unavailable. Training load still calculates from HR zones.

Watches with steps + HR only (no advanced physiology):

• Vivosmart 4, 5
• Vivofit 4, Jr. 3
• Lily (Gen 1, 2)

Steps, heart rate, and sleep duration are available. Advanced training metrics (VO2 Max, Training Status, Body Battery) will not be populated.

Note: Pacer handles missing data gracefully — sensors for unavailable metrics simply show as "Unknown" in Home Assistant.

Garmin limits OAuth logins but not token refreshes. Once authenticated, saved tokens in /data/garmin-tokens/ make every later sync a refresh (not a login). Problems arise on fresh installs where the addon falls back to garmin_email/garmin_password logins.

Fix: stop the addon, wait 15–30 minutes (up to 1–2 h if it re-fails), and start again for one clean login; tokens are then re-saved. Avoid frequent uninstall/reinstall cycles — a normal reinstall restores the tokens from /share/pacer/garmin-tokens/ automatically.

First check the Log tab. If you see No Garmin credentials or saved tokens — skipping auto-sync, run Settings → Connect Garmin to authenticate. The first sync pulls up to 6+ years of history and takes 30–45 minutes (rate-limited); watch progress via Settings → Sync Now. Subsequent syncs take ~30 seconds.

MFA codes expire after ~60 seconds — enter them promptly. OAuth tokens expire after roughly a year; re-authenticate from Settings → Connect Garmin.

All data is stored in PostgreSQL at /data/postgresql/ and backed up after every sync and on shutdown.

On reinstall with an empty database, Pacer restores the database and tokens from /share/pacer/ automatically — no manual step needed.

Every metric uses published, peer-reviewed formulas verified by automated accuracy tests. Stress and HRV are read directly from your Garmin watch — identical to what Garmin Connect shows.

Key takeaways: Stress & HRV are the exact Garmin numbers; Strain uses the same 0–21 scale as WHOOP (±1–2); VO2max & Readiness trends match Garmin/WHOOP but absolute values differ by 5–10%. Every formula is open-source — no black box. Sources: Banister (1991), Hulin et al. (2016), Uth et al. (2004), Cooper (1968), Riegel (1981), Hausswirth & Mujika (2013), Hirshkowitz et al. (2015), Moore (2016).

This repository is self-contained. The add-on packaging lives in pacer/ and the Next.js / tRPC / Drizzle application it serves lives in pacer/app/, built from local source by the Dockerfile. See CLAUDE.md for the layout and architecture notes.

• Docker

# Build the addon Docker image
./scripts/build-local.sh
# Build and run (accessible at http://localhost:3100)
./scripts/build-local.sh --run
# Remove built images
./scripts/build-local.sh --clean

# From the repository root
python -m pytest tests/ -v

CI runs a multi-stage Docker build (Node.js builder → HA base image) and pushes multi-arch images (amd64 + aarch64) to GHCR; tagged releases create GitHub Releases. A release-gate workflow refuses to ship addon images when the app repo's main checks are not green.

Contributions are welcome! Please see CONTRIBUTING.md for repository structure, local development setup, AI backend details, and the release process.

This project is not affiliated with, endorsed by, or connected to Garmin Ltd. or any of its subsidiaries. "Garmin", "Garmin Connect", "Body Battery", "Training Status", and related trademarks are the property of Garmin Ltd.

Pacer is an independent, community-developed project that reads publicly available user data from the Garmin Connect API. Use at your own risk.

This project is licensed under the Apache License 2.0. See LICENSE for the full text.

SPDX-License-Identifier: Apache-2.0