Bring your running, cycling, and other workout data from Garmin, Coros, Strava, Oura, and Apple Health into Home Assistant as native sensors — steps, heart rate, HRV, sleep, recovery, training load, VO2max/personal bests (where available), readiness/sleep/activity scores (Oura), and long-term statistics for charting aggregated activity over time (monthly running distance, year-to-date totals, year-over-year comparisons). Each run or ride also shows up as a calendar event with a full per-km split breakdown (pace, heart rate, power, cadence, elevation per km, where the source provides it), and every sensor this integration creates can be exposed to an AI assistant/MCP client via Home Assistant's own Model Context Protocol Server integration — see Letting an AI assistant query your data below.
A free, open-source Home Assistant custom integration, installed from
Home Assistant's built-in Marketplace (2026.11 and later) or
HACS (earlier versions). You can add Garmin, Coros,
Strava, Oura, Apple Health, or any combination — each is a separate config
entry with its own source-prefixed sensors (sensor.garmin_*,
sensor.coros_*, sensor.strava_*, sensor.oura_*,
sensor.apple_health_*), so data from each source can be charted separately
or side by side.
- Garmin Connect — Garmin's official Personal API (a self-serve API key you generate yourself in Garmin Connect's own settings — no developer account, app registration, or approval needed; see Garmin setup below).
- Coros — email/password login (unofficial API, no developer account required), plus an optional second connection for steps/sleep/HRV/recovery/ fitness assessment/training load (see Coros setup below).
- Strava — OAuth2, using your own Strava API application (see Strava setup below). As of Strava's June 2026 developer program change, this requires an active paid Strava subscription (e.g. USD$11.99/mo or AUD$14.99/mo) on the account that owns the API application — this is Strava's policy, not something this integration can work around. Without a subscription, Strava marks the application "Inactive" and rejects requests with a 403 error even after a successful sign-in.
- Oura (beta — not yet tested against a real account, see Oura setup below) — a self-serve Personal Access Token you generate yourself in your Oura account's own settings (no developer account, app registration, or OAuth approval needed). Provides daily Readiness/Sleep/Activity scores, sleep-stage detail, steps, and workouts — no per-km/mile split data (Oura's API has none).
- Apple Health — via a webhook pushed from an iOS Shortcut (see Apple Health setup below). Apple doesn't offer a cloud API for Health data, so this works by receiving workouts from your phone rather than pulling them. There's no depth setting to choose like Garmin/Coros/Strava/Oura's backfill — instead, the Shortcut's "Get Workouts" action returns your full on-device workout history the first time it runs, so your existing history arrives all at once as soon as you run it.
- Google Fit / Fitbit — not currently supported (Fitbit's legacy API was retired by Google in November 2026, and its replacement, the Google Health API, isn't yet open to new third-party developer projects).
-
Install "HA Workouts":
- Home Assistant 2026.11 or later: go to Settings → Marketplace, search for "HA Workouts" and install it. The first time, you'll be asked to accept the Marketplace's risk notice.
- Earlier versions: in HACS, search for "HA Workouts" and install it. It's in the default HACS repository, so no custom repository needs adding.
Already installed through HACS? Upgrading Home Assistant to 2026.11 moves it into the Marketplace automatically, with updates carrying on as before.
-
Restart Home Assistant.
-
Go to Settings → Devices & Services → Add Integration, search for "HA Workouts".
-
Choose a source (Garmin, Coros, Strava, Oura, or Apple Health) and follow the prompts — see Garmin setup / Coros setup / Strava setup / Oura setup (beta) / Apple Health setup below.
-
For Garmin, Coros, Strava, and Oura: choose how far back to import history. This backfill runs in the background after setup finishes — for several years of history it can take several minutes (see History backfill below) — and can be extended later without redoing it via the integration's Configure option. (Apple Health has no depth to choose — see Apple Health setup below for how its history arrives instead.)
-
To add another source, repeat from step 3 (e.g. add Garmin, then run setup again and add Coros, Strava, Oura, and/or Apple Health).
This integration uses Garmin's own official Personal API — your account password is never entered into Home Assistant. Instead you generate a Personal API key yourself:
- Sign in at connect.garmin.com.
- Go to Settings → Personal API Key (direct link).
- Click Create Key, accept the terms, and choose how long it should last (30/90/180 days, or 1 year).
- Copy the key shown — it's only displayed once.
- Paste it into this integration's setup form.
The key eventually expires (whatever duration you chose, up to 1 year) and there's no automatic renewal — Garmin's Personal API has no refresh token. When it expires, every sensor will start reporting an authentication error. To fix it: generate a new key the same way above, remove this integration's Garmin entry, and re-add it with the new key.
Two real feature gaps versus Garmin's old unofficial API: VO2max and Training Readiness (score/level/feedback) both have no equivalent in the official Personal API — confirmed by direct testing (checked 50 real activities, zero returned a VO2max value, despite Garmin Connect's own app clearly showing one) that this data lives in an internal Garmin service the Personal API simply doesn't expose, so those sensors don't exist for this source. Everything else (steps, HRV with status, sleep with stage detail, body battery, activities, and per-km/mile splits) is available, and some of it is richer than the old unofficial API exposed.
Garmin doesn't publish a rate limit for the Personal API, so this integration paces its requests conservatively regardless (see Rate limits below).
Enter your Coros account email and password — no developer account or API key
needed. This uses the same unofficial API Coros's own training.coros.com
web dashboard uses to sign in.
Region: you'll be asked to pick Global (default), Europe, or China. Almost every account, regardless of where you actually live, uses Global — Europe and China are genuine exceptions for accounts specifically registered there. If setup fails after picking one, try Global first, then the other two.
Important — logging in here signs you out of the Coros app. Coros only allows one active session per account, so connecting here will sign you out of the Coros phone app/Training Hub website, and logging into either of those later will sign this integration back out in turn. This isn't something this integration can avoid — it's how Coros's own session system works. If that's not acceptable, this Coros source may not be a good fit for you; there's no bundled/shared workaround.
Coros's activity data (distance, pace, splits — the part set up above) comes from a completely different part of their systems than steps, sleep, HRV, recovery status, fitness assessment, and training load. Those need a second, separate connection — Coros's official "COROS MCP" program — using the same email/password, but a genuinely different login mechanism that does not sign you out of anything (no session conflict with either the connection above or the Coros app).
You'll be offered this as an extra step right after entering your Coros credentials during setup ("Connect Coros health & fitness data") — tick the box to connect it there and then, or skip it and connect it later from Configure on the Coros integration entry (a checkbox appears there for as long as it isn't connected yet).
This unlocks these additional sensors, none of which any other source in this integration provides:
sensor.coros_steps,sensor.coros_active_caloriessensor.coros_sleep_score,sensor.coros_sleep_durationsensor.coros_recovery,sensor.coros_recovery_level,sensor.coros_estimated_full_recoverysensor.coros_training_load_short_term,sensor.coros_training_load_long_termsensor.coros_threshold_pace
Note on what's not included: Coros's own phone app shows a VO2max estimate and race-time predictions (5K/10K/half/full marathon) under "Running Fitness." As of this integration's testing, Coros's own official API doesn't return those specific figures yet, even though the app clearly has them — this is a gap in Coros's API, not something this integration can work around, so no sensors are offered for them. If Coros starts exposing that data, sensors for it can be added without any other changes.
Any of these can legitimately show "unknown" rather than a number — e.g. HRV if your specific watch model doesn't record it overnight, or steps if you don't wear the watch day-to-day. That's Coros genuinely having nothing to report, not a fault in the integration.
Strava requires you to register your own API application — this integration never uses a shared/bundled key:
- Go to strava.com/settings/api and create an API application.
- Set Authorization Callback Domain to your Home Assistant's domain
(e.g.
homeassistant.localor your external hostname — nohttps://and no path). - Copy the Client ID and Client Secret shown on that page.
- In Home Assistant, go to Settings → Devices & Services → Application
Credentials, add an entry for
ha_workouts, and paste in the Client ID and Secret. - Make sure the Strava account that owns this API application has an active Strava subscription. Otherwise the app shows as "Inactive" and the integration fails to connect with a 403 error immediately after you authorize — this is the single most common setup failure, see Troubleshooting.
- Continue the HA Workouts config flow — you'll be redirected to Strava to authorize access, then back here to finish setup.
Oura support is new and currently in beta — every field and endpoint used was verified against Oura's own published API documentation, but it hasn't yet been tested against a real Oura account (the author doesn't own a ring). If you try it, please open an issue with anything that looks wrong — it helps a lot.
Oura uses a Personal Access Token — no app registration, no OAuth, no Application Credentials step:
- Sign in at cloud.ouraring.com and go to Personal Access Tokens.
- Click Create A New Personal Access Token, give it a name (e.g. "Home Assistant"), and click Create.
- Copy the token shown — it's only displayed once.
- Start the HA Workouts config flow, choose Oura, and paste the token in.
If you revoke the token in your Oura account later, generate a new one the same way and re-add this integration with it.
Oura provides daily Readiness, Sleep, and Activity scores, sleep-stage detail (deep/REM/light sleep, heart rate and HRV during sleep), steps, and any workouts logged in the Oura app as calendar events — but no per-km/mile split data (Oura's API has none).
Apple Health/HealthKit has no cloud API, so there's nothing to poll — instead, the integration generates a webhook URL during setup, and an iOS Shortcut on your phone pushes each workout to it.
- Start the config flow and choose Apple Health. HA Workouts generates a webhook URL and shows it to you — copy it (you can view it again later from the integration's Configure option if you need it, e.g. for a second phone).
- Install Toolbox Pro (Paid App - Small amount) on your iPhone. Stock Shortcuts can only read raw daily quantity totals (e.g. "Walking + Running Distance"), which lump incidental walking in with real workouts and carry no per-session date — Toolbox Pro's Get Workouts action is what gets real structured workout records (type, distance, duration, calories) out of HealthKit.
- Get the Shortcut itself — two options:
- Use the pre-built Shortcut (easiest): open this share link on your iPhone and tap Add Shortcut. The first time it runs, it'll ask you to paste in a webhook URL — paste the one from step 1. Skip to step 4.
- Or build it yourself: create a new Shortcut with:
- Get Workouts (from Toolbox Pro) to fetch your workout history.
- For each result, build a dictionary with keys (all set to
Text):id— the workout's unique identifier (used to avoid double-counting if the Shortcut runs again over the same workout)type— e.g.Running,Cycling,Walking,Swimming,HikingstartDate/endDateduration— in minutesdistance— with unit, e.g.11.4 km(also acceptsmi)calories— with unit, e.g.724 kcal
- Get Contents of URL: method
POST, URL = the webhook URL from step 1, request body = that dictionary, encoded as JSON.
- Set the Shortcut to run automatically without confirmation prompts — e.g. a Shortcuts Automation (time of day, or "when app closes" for a fitness app) with Ask Before Running turned off, so it can post in the background.
- Finish the config flow. The first time the Shortcut runs, matching
per-activity-type sensors (e.g.
sensor.apple_health_running_distance_km) appear and start reporting. Since Toolbox Pro's Get Workouts returns your full on-device workout history (not just new workouts), the first run typically posts your whole existing history in one go — there's no separate backfill step to configure like Garmin/Coros/Strava. - Optional - Create an automation to run every
xdays to run the shortcut to keep your data updated. Alternatively, create an automation to run the shortcut whenever you complete a workout.
Get the workouts
Setting up the data (make sure all fields are Text)
- Daily summary sensors (Garmin only — Coros/Strava/Apple Health have no equivalent): steps, resting heart rate, active calories, floors climbed, average stress, body battery, and HRV (last night average, 7-day average, status). VO2 max and Training Readiness are not available — Garmin's official Personal API has no equivalent to either of the old unofficial API's values (see Garmin setup).
- Coros health & fitness sensors (only if you connected the optional second MCP connection — see Coros setup): steps, active calories, sleep score/duration, HRV (last night/7-day average), recovery (percent, level, estimated full recovery time), training load (short-term/long-term), threshold pace.
- Per-activity-type sensors, source-prefixed, e.g.
sensor.garmin_running_distance_km,sensor.coros_running_distance_km,sensor.strava_cycling_duration_minutes,sensor.apple_health_running_distance_km: a lifetime-cumulative running total (like an odometer, not "today's total") for distance/duration/calories per activity type. Its chart history lives in a matching statistic (see Charting your data) — the cumulative value itself isn't meant to be read directly. - Last activity: name, type, duration of your most recent workout. Garmin also gets running-form, power, and training-load detail for the most recent activity: running/cycling cadence, power (average, max, normalized), vertical oscillation, ground contact time, aerobic/anaerobic training effect, training load, and fastest 5K/10K split within the activity.
- History import status (
..._history_import_status, Garmin/Coros/Strava only): shows backfill progress (idle/running/backing_off/complete/error) and how far back it's reached — useful to watch during a large first-time import. See History backfill. Apple Health doesn't have this sensor — its history arrives directly via the Shortcut rather than a paced background job, so there's no progress to report.
This integration doesn't ship its own MCP server — it doesn't need to. Home Assistant has a built-in Model Context Protocol Server integration that can expose any entity you choose, including every sensor this integration creates, to an MCP-capable AI assistant (Claude, etc.). Once set up, you can ask things like "what was my training load on my last run?" or "how many km have I run this month?" and the assistant can look up the real answer from your actual sensors.
Setup:
- Settings → Devices & Services → Add Integration, search for "Model
Context Protocol Server", and add it. This creates a
/mcp_server/sseendpoint secured by a Home Assistant long-lived access token. - Choose which entities it can see via Settings → Voice assistants →
Expose (the same exposed-entities list Assist uses) — tick the
ha_workoutssensors you want queryable (e.g.sensor.garmin_running_distance_km,sensor.garmin_last_activity_training_load,sensor.coros_threshold_pace). Only exposed entities are visible over MCP — nothing is exposed by default. - Generate a long-lived access token for your Home Assistant user
(Profile → Security → Long-lived access tokens) and configure your
MCP client (Claude Desktop, Claude Code, etc.) to connect to your Home
Assistant's
/mcp_server/sseendpoint with that token — see Home Assistant's own MCP Server docs for the exact client-side configuration, which varies by MCP client.
Once connected, the assistant can read (and, depending on what you expose,
act on) any exposed ha_workouts entity like any other Home Assistant
entity — no special handling needed on this integration's side, since it's
just sensors like any other.
Most charts below use Home Assistant's built-in Statistics Graph and Statistic cards. Comparing one year's months against another's needs the community ApexCharts Card.
Pick the statistic, not the sensor. Each per-activity-type sensor's
history is stored in a statistic named after its source, e.g. Garmin
running distance km (ha_workouts:garmin_running_distance_km). In the card
editor, pick that statistic. The sensor.garmin_running_distance_km entity
only shows the live running total and has no chart history of its own.
- Edit a dashboard → + Add Card → search "Statistics Graph".
- Set:
- Statistics: Garmin running distance km
(
ha_workouts:garmin_running_distance_km) - Period: Month
- Stat type: Change
- Graph type: Bar
- Statistics: Garmin running distance km
(
- Save.
"Change" is what turns the cumulative total into a per-period bar chart.
It's the difference between consecutive period boundaries, not the raw
running total. This also works with _duration_minutes or _calories, and
with Period: Day or Period: Week for finer granularity.
Use the sensor.garmin_running_yeartd sensor (also _weektd and
_monthtd). It's calculated straight from your activities and resets at the
start of each year. Show it with an Entity or Tile card.
Add multiple statistics to one Statistics Graph card, e.g. Garmin running distance km and Apple Health running distance km (if you use both), or Garmin running distance km and Garmin cycling distance km, to overlay them on the same chart.
The ha_workouts.get_monthly_totals action returns 12 monthly totals for
each year you ask for, calculated from your stored activities. Try it in
Developer Tools → Actions:
action: ha_workouts.get_monthly_totals
data:
source: garmin # garmin, strava, coros or apple_health
activity_type: running
metric: distance_km # distance_km, duration_minutes, calories or activity_count
years: [2025, 2026] # optional, defaults to last year and this yearunit: km
years:
"2025": [42.1, 38.5, 51.0, 47.3, 55.2, 60.8, 58.4, 49.9, 44.0, 52.7, 40.3, 36.6]
"2026": [45.3, 41.0, 57.2, 50.1, 61.4, 63.0, 59.8, 54.2, 48.7, 55.1, 12.4, null]Months that haven't happened yet are null, so charts stop at today.
Built-in Home Assistant cards can't call an action, so use
ApexCharts Card. Install it
from Settings → Marketplace (or HACS before 2026.11). Each series calls
the action and places its 12 values on this year's months, so the years line
up as grouped bars. Change garmin, running and the years to suit:
type: custom:apexcharts-card
header:
show: true
title: Running km by month
graph_span: 1y
span:
start: year
apex_config:
xaxis:
labels:
format: MMM
series:
- entity: sensor.garmin_running_yeartd
name: "2025"
type: column
data_generator: |
const year = 2025;
const r = await hass.callWS({
type: "call_service",
domain: "ha_workouts",
service: "get_monthly_totals",
service_data: { source: "garmin", activity_type: "running",
metric: "distance_km", years: [year] },
return_response: true,
});
const now = new Date().getFullYear();
return r.response.years[year]
.map((v, i) => [new Date(now, i, 15).getTime(), v]);
- entity: sensor.garmin_running_yeartd
name: "2026"
type: column
data_generator: |
const year = 2026;
const r = await hass.callWS({
type: "call_service",
domain: "ha_workouts",
service: "get_monthly_totals",
service_data: { source: "garmin", activity_type: "running",
metric: "distance_km", years: [year] },
return_response: true,
});
const now = new Date().getFullYear();
return r.response.years[year]
.map((v, i) => [new Date(now, i, 15).getTime(), v]);The entity: line is only there because ApexCharts requires one; any
ha_workouts sensor works.
The same action can show how your distance builds up over the year: one line per year, starting at 0 on 1 January and climbing month by month. Each point is the running total at the end of that month (or today, for the current month), so you can see whether you're ahead of or behind last year.
type: custom:apexcharts-card
header:
show: true
title: Running km, year to date
graph_span: 1y
span:
start: year
apex_config:
xaxis:
labels:
format: MMM
yaxis:
min: 0
series:
- entity: sensor.garmin_running_yeartd
name: "2025"
type: line
stroke_width: 3
data_generator: |
const year = 2025;
const r = await hass.callWS({
type: "call_service",
domain: "ha_workouts",
service: "get_monthly_totals",
service_data: { source: "garmin", activity_type: "running",
metric: "distance_km", years: [year] },
return_response: true,
});
const now = new Date();
const thisYear = now.getFullYear();
const points = [[new Date(thisYear, 0, 1).getTime(), 0]];
let total = 0;
r.response.years[year].forEach((km, month) => {
if (km === null) return;
total += km;
const monthEnd = new Date(thisYear, month + 1, 1).getTime();
const t = year === thisYear ? Math.min(monthEnd, now.getTime()) : monthEnd;
points.push([t, Math.round(total * 100) / 100]);
});
return points;
- entity: sensor.garmin_running_yeartd
name: "2026"
type: line
stroke_width: 3
data_generator: |
const year = 2026;
const r = await hass.callWS({
type: "call_service",
domain: "ha_workouts",
service: "get_monthly_totals",
service_data: { source: "garmin", activity_type: "running",
metric: "distance_km", years: [year] },
return_response: true,
});
const now = new Date();
const thisYear = now.getFullYear();
const points = [[new Date(thisYear, 0, 1).getTime(), 0]];
let total = 0;
r.response.years[year].forEach((km, month) => {
if (km === null) return;
total += km;
const monthEnd = new Date(thisYear, month + 1, 1).getTime();
const t = year === thisYear ? Math.min(monthEnd, now.getTime()) : monthEnd;
points.push([t, Math.round(total * 100) / 100]);
});
return points;As in the bar chart, both years are drawn on this year's dates so the lines sit on top of each other. Last year's line runs to December; this year's stops at today.
Applies to Garmin, Coros, and Strava only. Apple Health's existing history arrives a different way — via the Shortcut's first run, which returns your full on-device workout history in one batch (see Apple Health setup) — rather than this paced, gap-aware background job.
On first setup (and whenever you increase the configured depth via Configure), the integration fetches your past activity history and imports it into Home Assistant's long-term statistics — this is what makes the charts above useful immediately instead of starting from an empty graph.
- Depth options range from 90 days to "all available history." Longer ranges mean more API requests to your source, paced conservatively (see below), so a multi-year backfill can take several minutes.
- For "all available history," the backfill stops automatically once it
finds several consecutive empty chunks — it doesn't walk all the way back
to the 1970s for an account with only a few months of real data. The
earliest day it actually found is shown on the
..._history_start_datesensor. - Progress is visible on the
..._history_import_statussensor. - It's gap-aware and self-healing: if Home Assistant restarts mid-backfill, the next run detects any incomplete range and re-fetches it rather than leaving a permanent hole in your history.
- Increasing the depth later only fetches the newly-uncovered older days — it doesn't redo the whole import.
Coros's API is unofficial and undocumented, and Garmin's official Personal
API doesn't publish a request quota either, so this integration paces
backfill requests conservatively for both (15–20s between request batches)
to avoid triggering rate limiting — which, if hit, can lock out all API
access for that account for an extended period, not just the backfill.
Strava's documented limits are more generous so its pacing is lighter. If
you see the history import sensor show backing_off, this is expected
behavior after a rate limit, not an error — it will retry automatically.
Strava: "Strava rejected the request with a 403... status Inactive" — the Strava account that owns your API application doesn't have an active paid Strava subscription. Subscribe on that account, reactivate the app at strava.com/settings/api, then retry setup. See Strava setup above.
Garmin: repeated "429 Too Many Requests" / integration stuck retrying — Garmin has rate-limited the account, usually from a burst of requests in a short window (e.g. a large history backfill combined with other activity). Home Assistant retries automatically with increasing backoff; it typically clears within 30–60 minutes of being left alone.
Garmin/Oura/Coros: a "Reauthenticate" notification appears, or the entry shows as needing attention under Devices & Services — the stored credential was rejected (an expired/revoked Garmin API key or Oura token, or a genuinely wrong Coros password — not the normal "someone else logged into the Coros app" case, which self-heals automatically). Click the notification, or open the integration and click Reconfigure, and enter a fresh credential — see Garmin setup / Oura setup / Coros setup for where to get a new one. No need to remove and re-add the entry.
Coros: "Coros session expired or was invalidated" repeatedly — most often means you (or another device/app) logged into the Coros app or Training Hub website, which silently ends this integration's session — Coros only allows one active login at a time (see Coros setup). The integration will automatically log back in on its next poll; this doesn't affect the separate optional MCP connection for health/fitness data, if you have one connected.
Coros: setup fails no matter which region I pick — double check you're actually entering your Coros account's email/password correctly first (a wrong password can also manifest as a region-shaped failure). If you're confident the credentials are right, try all three region options in turn — this integration cannot detect your account's real region automatically (see Coros setup).
A Statistics Graph card shows a big spike or drop on one day — this generally means the underlying statistics history has a gap or was imported before a fix to this integration. For Garmin/Coros/Strava, increasing then re-saving the backfill depth in Configure triggers a fresh, self-healing import (see History backfill). For Apple Health, which doesn't have a backfill setting to re-trigger, re-run the Shortcut to resend the affected workouts instead.
"All available history" stops at a date that's clearly wrong — real, older activity exists before it — versions before v0.15.1 had a bug where, if your most recent ~9 months of activity were empty (e.g. returning from a long break, or a freshly-connected account that had been idle), the automatic "how far back does real history go" detection could give up before ever reaching your actual older history, and permanently cache that wrong cutoff (see the History start date sensor). This is fixed going forward, but a bad cutoff cached by an earlier version won't correct itself automatically. To fix it: open Configure on the affected entry and set Earliest activity date to the real date your history starts (or earlier — extra headroom doesn't cost anything, the detection logic will walk forward from there and find the real boundary on its own), then save. This field is optional and only used for "All available history" — leave it blank otherwise.
Apple Health: the Shortcut runs but no data shows up — first confirm the
webhook URL is actually reachable from your phone: open it directly in
Safari on the phone (not just in a browser on the same computer running HA).
A working webhook returns a plain-text OK or Ignored (duplicate) — Safari
may show this as a zero-byte "download," which is expected and means the
request succeeded, not a failure. If the URL doesn't load at all, check
Settings → System → Network → Internal URL in Home Assistant is set to
an address your phone can actually reach (e.g. your HA instance's LAN IP,
not localhost), and regenerate the Shortcut's URL from Configure on the
Apple Health integration entry afterwards.
Apple Health: workouts appear twice, or a huge batch of history lands at
once — the first time you run a "Get Workouts"-based Shortcut, Toolbox Pro
returns your entire on-device workout history, not just new workouts, so
expect a large batch to post all at once on the first run. Re-running the
same Shortcut later is safe: each workout carries a stable id, and this
integration ignores anything it's already seen since the last Home Assistant
restart.
This repo includes a docker-compose.dev.yml for running a local Home
Assistant instance with the integration bind-mounted, so code changes are
picked up on restart without reinstalling anything:
docker compose -f docker-compose.dev.yml up -d
# HA available at http://localhost:8123pip install -r requirements-dev.txt
ruff check custom_components/ha_workoutsmodels.py— source-agnostic data model (Activity,DailySummary,FitnessAssessment,BodyComposition)sources/base.py—WorkoutSourceinterface each provider implementssources/garmin.py— Garmin Connect implementation, against Garmin's official Personal API (a self-serve, individual-use API key — see Garmin setup)sources/coros.py— Coros implementation, against the same unofficial Training Hub APItraining.coros.comitself uses (activities, splits, and a rough HRV figure); optionally augmented bysources/coros_mcp.pysources/coros_mcp.py— client for Coros's official OAuth2 + MCP program ("COROS MCP"): Dynamic Client Registration, a fully server-to-server login flow (no browser/external step despite being real OAuth2 — see that module's docstring), token refresh, and JSON-RPC tool calls. Used only for the handful of health/fitness metrics Training Hub doesn't expose at all (steps, sleep, HRV assessment, recovery, fitness assessment, training load) — an entirely separate, optional login fromsources/coros.py's, with no session conflict between the twosources/coros_mcp_parsers.py— parses Coros MCP's free-form prose tool responses (not JSON — seecoros_mcp.py's docstring for why) intoDailySummary/FitnessAssessmentfields; each parser returnsNonefor anything it can't find rather than raising, so an unrecognized wording degrades a sensor to "unknown" instead of crashing the daily pollsources/strava.py— Strava implementation (OAuth2 via Application Credentials)sources/apple_health.py— Apple Health implementation; a push receiver rather than a poller, parses webhook payloads from an iOS Shortcut intoActivityobjects and queues them for the coordinatorapplication_credentials.py— declares Strava's OAuth2 endpointscoordinator.py— pollingDataUpdateCoordinator, fetches today's data (or, for Apple Health, drains whatever's arrived via webhook since the last poll)statistics_import.py— gap-aware historical backfill into HA's long-term statistics tables for Garmin/Coros/Strava, plusasync_apply_activity_deltas, which folds newly-seen activities into the same statistics tables keyed by each activity's own real date — used for every live update, and the only path Apple Health ever writes through, since it has no separate backfillconfig_flow.py— source picker, Garmin form, Coros form (plus its optional MCP-connect sub-step), Strava OAuth2 flow, Apple Health webhook generation, backfill depth selection for Garmin/Coros/Strava (initial + reconfigurable via Options, which is also where Coros MCP can be connected after the fact if skipped during setup)__init__.py— registers the Apple Health webhook endpoint and its request handler, alongside general entry setup/teardownsensor.py— daily summary, per-activity-type, HRV, Coros MCP, and backfill status entities
Adding a new source means implementing WorkoutSource in sources/ and
wiring it into config_flow.py and __init__.py's _build_source.


