A new open-source project called garmin-ai-notifier dropped on GitHub this week, and it's exactly the kind of hack that makes you wonder why nobody built it sooner. The tool pulls your complete Garmin Connect history into a local SQLite database, runs percentile analysis across all your data, feeds it to Google Gemini, and delivers a coached daily brief straight to your phone via ntfy, Telegram, or email — all running on GitHub Actions for zero dollars.

How the Pipeline Works

The system runs three main stages each morning. First, src.pull.py fetches recent days from Garmin Connect using the garminconnect Python library and updates your local database. Next, features.py crunches the numbers — computing 30-day averages, spotting trends (worsening vs improving), identifying streaks near all-time lows, and flagging records like intensity minutes hitting an all-time high. Finally, insight.py sends a structured digest to Gemini, which generates natural language coaching: "In bed 30 minutes earlier tonight" or warnings about cortisol spikes from poor sleep.

The Tech Stack

This is a Python project through and through — no flashy frontend, just pure automation engineering. It requires python3.12, the garminconnect library for API access, Google's generative-ai package for Gemini integration, and SQLite for persistence. GitHub Actions handles scheduling (runs at 13:00 UTC daily) and commits the updated database back to your repo on each run. The developer notes that committing garmin.db prevents GitHub from auto-disabling workflows after 60 days of inactivity — a clever workaround that's worth knowing if you automate anything on CI.

Privacy-Conscious Design

The project makes deliberate choices about what stays out of the database. No GPS coordinates, no activity routes, no raw API responses, and no heart-rate streams — just scalar daily wellness metrics: steps, resting HR, sleep duration and score, stress levels, Body Battery high/low, HRV, training readiness, intensity minutes, and active calories. The date field stores YYYY-MM-DD only. This means your garmin.db is relatively safe to commit publicly if you want a free GitHub-hosted runner. Fitness age refers to Garmin's estimated metric, not your actual birthdate.

Getting Started

Setup requires four steps: creating a Python virtual environment and installing requirements; minting a Garmin token locally (valid roughly one year); backfilling 180 days of history into garmin.db with BACKFILL_DAYS=180 python -m src.backfill; and configuring GitHub Actions secrets including GEMINI_API_KEY, NOTIFIER settings, and base64-encoded Garmin tokens. The developer provides scripts/mint_token.py for secure credential handling and pack_tokens.sh to bundle everything safely.

Watch Out For

A few gotchas worth noting: Gemini's free tier may use inputs for training (the digest contains only aggregated numbers with no names or emails); tokens expire around yearly so you'll need to re-run mint_token.py when authentication fails; one Gemini call per day means flash → flash-lite fallback on rate limit errors; metrics under 14 days of data skip percentile and record claims entirely. If you hit "limit: 0 429" errors, link a billing account to the GCP project tied to your API key — it stays within free tier limits for one daily call.

Key Takeaways

  • Runs completely free on GitHub Actions with no server maintenance required
  • Stores only scalar daily metrics — no GPS, routes, or raw activity data
  • Uses Gemini flash model with automatic fallback to flash-lite on rate limits
  • Commits garmin.db daily to prevent workflow auto-disable after 60 inactive days

The Bottom Line

This is the kind of project that demonstrates what's possible when you chain together free-tier APIs with CI automation — no vendor lock-in, no subscription fees, just elegant plumbing. If you've been sitting on Garmin data without doing anything useful with it, this is your wake-up call (literally). Hackers have been building personal data pipelines for years; now your fitness tracker finally gets the same treatment.