Long Run Hybrid Coach

繁體中文 · English · 简体中文

Long Run Hybrid Coach is an unofficial, Intervals-first, device-agnostic personalized hybrid training coach. It maintains a single 28-day direction plus this week's running and strength training plan, reads trusted actual completion evidence for continuous review, and can push the plan to the Intervals.icu calendar after you confirm.

Garmin is not a prerequisite. Garmin is currently the first downstream device path that has been dogfooded on real hardware; Apple Watch, COROS, Polar, Suunto, Wahoo, other apps/watches, or even no watch at all, can all use the same Coach. The difference lies in how much trusted evidence can enter the training loop, and whether the device sync path behind Intervals has been verified.

General users should prefer Hosted MCP: https://mcp.paceandstaystrong.com/mcp. You need an Intervals.icu account, but you don't need to create your own Intervals OAuth App or operate your own gateway.

Quick Start: Hosted MCP

What do you need before using it?

1. An Intervals.icu account.

2. An AI client that can connect to a remote MCP and supports the actions this product requires.

3. Optional: a watch or training app that already syncs activities into Intervals.icu.

It works without Garmin. When there's no automatic recovery evidence, the Coach treats missing data as unknown, not 0.

1. Connect to the Hosted Coach

MCP endpoint:

https://mcp.paceandstaystrong.com/mcp

• claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → paste the endpoint. This path has been fully verified in production for OAuth, coaching turns, and Intervals delivery.

• ChatGPT: Full MCP (including write/modify actions) is currently available as a beta for ChatGPT Business, Enterprise, and Edu web versions per OpenAI's official documentation; Pro's custom MCP currently only supports read/fetch and cannot complete this Coach's full plan write/delivery flow. If your workspace supports full MCP, create a custom app in Apps/developer mode and point it at the remote endpoint above. For the latest plan limitations, refer to OpenAI's official documentation.

• OpenClaw: Use openclaw mcp add to point to the same endpoint, and add --auth oauth; if an instance is used by more than one person, set the OAuth identity to per-requester, otherwise everyone will connect to the same Intervals account. See entrypoints/openclaw/ for setup.

• Other MCP clients: Set the same URL as a remote Streamable HTTP MCP server; whether the full flow actually works depends on whether that client supports the MCP/OAuth behaviors this product requires.

For the per-entry status of "fully verified on real hardware" or "packaged, awaiting real connection verification," refer to entrypoints/.

2. Authorize Intervals.icu

On first connection, the browser will open the Intervals.icu consent page. Log in with your own Intervals.icu account and authorize the capabilities the Coach needs:

• ACTIVITY:READ: read completed workouts.

• WELLNESS:READ: read wellness evidence available from Intervals.

• CALENDAR:WRITE: read/write the training calendar, so confirmed plans can be delivered and verified via read-back.

• SETTINGS:WRITE: read settings; only fill in a missing running threshold setting that is supported by evidence when the confirmed delivery flow actually requires it.

Intervals' consent page separates the permissions. If you skip one, the capabilities that depend on it will fail explicitly; just reconnect and add the permission. Do not paste your Intervals password, API key, or token into the conversation.

3. Just ask normal coaching questions

No need to fill out a questionnaire first, for example:

讀我最近的訓練，告訴我這週該怎麼練。

or:

我想提升 VO2max，又不想掉力量，幫我排第一個 28 天方向。

The Coach will first read existing evidence, then only ask about gaps that would actually change a decision, such as available training days this week, equipment, or strength training baselines that the provider cannot know.

4. Look at the 28-day preview first, then confirm the plan

When creating a plan for the first time, you'll see:

• This week: precise, executable, deliverable sessions.

• Next three weeks: directional outlook, without pretending to know all the details now.

The plan is only written after you confirm that preview. Every subsequent weekly change follows the same experience:

before / after preview → one confirmation → apply.

5. Do a delivery confirmation only when sending to the calendar

Delivery is a separate, independent confirmation:

delivery preview → one confirmation → write to Intervals.icu → read-back verification.

The furthest state this product can prove is intervals_accepted. Intervals success does not mean the plan is already on Garmin, Apple Watch, or another watch. The sync behind Intervals is an external hop that must be verified per device path.

Related MCP server: Transition MCP

What does Intervals.icu do in this product?

Intervals.icu is the current interoperability hub: it helps the Coach receive activity and wellness evidence from different devices/apps, and also hosts the calendar plan after the Coach confirms it. It is not the Coach's PlanState source of truth.

手錶 / 訓練 app
      │
      ▼
 Intervals.icu ───── 已完成活動 + wellness evidence ─────► Coach
      ▲                                                   │
      │                                                   │
      └────────── 確認後的 calendar workout ◄────────────┘
      │
      ▼
Garmin / Apple Watch bridge / 其他下游同步

Division of responsibilities:

• Intervals.icu: integrates external training evidence and holds the provider calendar.

• Long Run Hybrid Coach: holds the single current PlanState, decision history, athlete-reported evidence, confirmation bindings, and coaching workflow.

• Your watch/app: can bring activities into Intervals and may receive workouts pushed down from Intervals; but whether the last mile succeeds is independent compatibility evidence.

Does Intervals need to have data in it first?

Only the account itself is required. If activities/wellness are already synced in, the Coach's automatic evidence will be more complete; fields that are missing remain unknown, are not treated as 0, and won't block general coaching just because one optional metric is missing.

Things the device can't measure or that aren't synced can be mentioned directly in the conversation, for example:

• Actual strength training sets, weights, and reps;

• Available training time and equipment constraints this week;

• Body weight/body fat;

• An activity done without a watch;

• Subjective states like "I'm really tired lately" or "sleeping poorly";

• Recovery readings you actually see on your watch/app, such as sleep, HRV, resting HR, readiness.

The Coach will not quietly turn a "I'm really tired" into a fake readiness score.

Hosted MCP vs Local / Self-hosted MCP

There's only one difference you'll actually feel: hosted works directly on your phone; local only works on the machine running the gateway. Every other line below is a cost of that difference.

Shortest activation flow for Hosted MCP

1. Add a remote MCP app/connector in an MCP client that supports the full requirements.

2. Paste https://mcp.paceandstaystrong.com/mcp as the URL.

3. Complete the client's OAuth flow.

4. Authorize in the browser on Intervals.icu.

5. Return to the chat and ask your first coaching question directly.

The hosted service handles dynamic client registration, PKCE, gateway tokens, and per-athlete owner mapping itself; general users don't need an owner id, athlete id, API key, Intervals client secret, or server environment variables.

How do I run Local / Self-hosted MCP?

The repo uses Python 3.11, and the product itself is stdlib-only—no need to install a bunch of runtime Python packages first.

1. Clone the repo.

2. Apply to Intervals.icu to create an OAuth application. Intervals' current public flow is not a self-service "add app" in Settings: per the official OAuth documentation, provide the app name, description, website, logo, privacy policy, redirect URI, and your Intervals ID; the app only appears in Settings after it's created, where you get the client_id/secret from Manage App. See Intervals.icu OAuth support for the flow.

3. Register the gateway provider callback in the Intervals app: <gateway-origin>/oauth/callback. A local client can use loopback; a remote client needs a reachable HTTPS/secure tunnel.

4. Set the required gateway environment variables:

export GARMIN_COACH_LOOP_GATEWAY_STATE_ROOT="$HOME/.local/share/long-run-hybrid-coach-gateway"
export GARMIN_COACH_LOOP_TOKEN_HMAC_KEY="$(openssl rand -base64 32)"
export GARMIN_COACH_LOOP_INTERVALS_CLIENT_ID="..."
export GARMIN_COACH_LOOP_INTERVALS_CLIENT_SECRET="..."

5. Start it:

python3 -m garmin_coach_loop.cli serve-gateway --host 127.0.0.1 --port 8422

6. Point your local MCP client at:

http://127.0.0.1:8422/mcp

If you're formally serving remote clients, don't treat the loopback example as a production runbook. Persistent volume, TLS, trusted client origin, single replica, release identity, and deployment verification are covered in docs/deploy-gateway.md.

Local CLI should not silently become a second current plan

An athlete should have only one current writer. When the local GARMIN_COACH_LOOP_GATEWAY_URL points to the hosted coach, local store writes are blocked by default; only explicitly adding --offline means "I'm deliberately working on a separate local plan."

People who already have local state can migrate to hosted; the full flow is in docs/ops/migrate-local-store-to-hosted.md.

What can it do now?

Current product capabilities include:

• Maintaining a 28-day direction: precise sessions for this week plus a three-week outlook.

• Reading Intervals activity/wellness/calendar evidence and automatically reconciling trusted planned → actual back into the current plan.

• Handling running and strength training together in the same weekly plan.

• Recording athlete-reported profile, availability, long-term goals, training preferences, actual strength work, body weight/body fat, activities the device didn't capture, and subjective states.

• startCoachSession accepts the recovery readings for the current request; Hosted doesn't need to—and won't—read your local health database.

• Importing supported historical evidence, including CSV in supported formats, Apple Health XML content, and FIT payloads handled through the binary import path; deterministic deduplication for the same file and same activity, asking the user only when it can't decide.

• Sessions can carry a coach_note, so the coach's key text goes into the Intervals event instead of quietly spawning a second workout grammar.

• Weekly review of "what was actually done, whether there's evidence of progress, and what's next," rather than treating "plan completed" as fitness gained.

• Plan changes are previewed first, then confirmed, then applied.

• Calendar delivery is previewed first, then confirmed; supports safe retry, replace, and withdrawal of product-owned events.

• Exporting directly in the conversation or two-stage permanent deletion of owner data held by this product.

Important boundaries

• startCoachSession performs deterministic reconciliation and may write a new PlanState version; if you want completely side-effect-free stored state, use getCoachState—that's the read-only path.

• Athlete-reported activity is evidence, but it won't be quietly promoted to provider-backed actual completion.

• Recovery numbers only accept real observed values; the model must not guess a number from text on its own.

• This product does not provide medical diagnosis.

• Delivery evidence only goes as far as Intervals read-back; it won't claim the plan is already on the watch.

Data, export, and deletion

The hosted side retains the product state necessary to maintain the same owner's plan: the PlanState version chain, decision/receipt, athlete-reported evidence, identity mapping, and unconverged delivery bookkeeping.

Exports deliberately exclude: the keyed fingerprint of OAuth credentials, provider raw payload/GPS tracks, and the internal owner id. The fingerprint is one-way bookkeeping; raw GPS/activity files should come from the provider; the owner id is an internal storage locator.

Deleting product data also has three clear boundaries—these three things are outside what this product can delete:

• Workouts already written to the Intervals.icu calendar;

• Provider authorizations you granted in Intervals.icu Settings;

• Minimal platform operations logs that contain no plan, health, or identity content.

See docs/account-lifecycle.md for the full lifecycle; the public privacy policy is at paceandstaystrong.com/privacy.html.

Current limitations

• The Coach does not log into Apple Health, Garmin Connect, or other device accounts directly; the primary automatic evidence path is currently still Intervals.icu.

• Hosted does not permanently store the raw recovery uploads from each request; send the current evidence again next time you need it.

• This product does not observe every device sync hop after Intervals, so it won't describe intervals_accepted as "already on the watch."

• Local self-hosting is an operator/developer path; general users should prefer Hosted MCP.

• Device compatibility is per-path evidence; just because Garmin is verified doesn't mean other devices are necessarily the same.

Product surface and technical documentation

The current release exposes 22 MCP tools, 2 prompts, 30 CLI commands, 3 JSON Schema contracts, and 5 identity tables. These counts are derived by tests from the actual code, so the README doesn't drift on its own.

• Stable user stories: docs/user-story.md

• Data sources and field boundaries: docs/data-sources.md

• Entry points and platform setup: entrypoints/

• MCP protocol, OAuth, and tool behavior: entrypoints/mcp/README.md

• Hosted gateway deployment: docs/deploy-gateway.md

• Account lifecycle: docs/account-lifecycle.md

• Public listing/reviewer materials: docs/distribution/

• Release inventory: docs/release-inventory.md

• Repository invariants and verification: AGENTS.md

Long Run Hybrid Coach is an independent project with no affiliation, endorsement, or sponsorship relationship with Garmin, Intervals.icu, Apple, or other device/platform vendors. The code is released under the MIT License.