health-setup

name

health-setup

description

Interactive setup wizard for the health-mcp connector. Picks the right wearable (Apple Watch / Apple Health, Oura Ring, Fitbit, Garmin, Whoop) and OS (macOS / Windows / Linux), walks the user through getting API tokens or exporting data, sets env vars, and verifies the connection end-to-end. Use when the user says /health-setup, asks to set up their wearable, asks "which wearable", asks how to import Oura or Fitbit, or after a fresh install of health-mcp.

health-setup, interactive wearable connector wizard

Walks the user from "I have an Apple Watch / Oura / Fitbit" to "data is in my DuckDB and I can run /weekly with body track populated."

The wizard branches by:

1. Which wearable(s) they have
2. Which OS they're on (macOS / Windows / Linux)
3. Whether they're starting fresh or adding a second device

It never installs anything they don't want. Each branch has its own setup path — most of them are 3-5 manual steps and a paste-into-shell to set env vars.

When to use

• User says /health-setup or /setup-health or setup my health connector
• User asks "how do I import Oura / Fitbit / my Apple Watch data"
• User says "which wearable should I use" — pick + walk through setup
• After a fresh install of the ai-brain-starter substrate
• After health-mcp v0.3+ is registered but no data is imported yet

Do NOT use for:

• Querying already-imported data (use health_status, health_recovery_score, etc.)
• Building new wearable connectors (that's a substrate dev task)
• Onboarding non-health skills

Wizard flow

Step 1: Detect the OS

Look for darwin / linux / a Windows path separator in the environment. Confirm with the user if uncertain. Map to one of: macos, linux, windows.

Step 2: Ask which wearable(s) they have

Multiple-select. The substrate currently supports first-class:

• Apple Watch / iPhone (Apple Health) — most common, free, works without iPhone-paired apps
• Oura Ring — free Personal Access Token, no app review needed
• Fitbit — free Personal app, slightly more setup (OAuth2)
• Garmin — sync to Apple Health on iPhone, then ingest via Apple Health path
• Whoop — deferred to v0.4

If they say "multiple" — that's fine, the substrate's shared DuckDB schema accepts data from all vendors. Run each vendor's setup in sequence.

If they say "I don't have one" — close the wizard. Recommend they journal manually + add labs (health_import_labs) for the parts of the substrate that don't need wearables.

Step 3: Run health_vendor_setup_guide for each chosen vendor

Call the tool with the vendor + OS:

health_vendor_setup_guide(vendor="oura", os_kind="macos")

The returned dict contains: display_name, summary, common_steps, transfer_steps (OS-specific), env_vars (with explanations), tool_to_run, ongoing_cadence, notes.

Render it to the user as numbered steps. Do NOT paraphrase the env-var commands — copy them verbatim, the user will paste them into their shell.

Step 4: Verify before importing

Once env vars are set and Claude Code restarted, run:

health_vendor_healthcheck(vendor="oura")   # for Oura
health_vendor_healthcheck(vendor="fitbit") # for Fitbit
health_status()                            # for Apple Health

Each returns either {ok: true, ...account-info} or {ok: false, error: "..."}. If ok: false, surface the error and walk back to the env-var step.

Step 5: First import

Once the healthcheck passes, run the vendor's import for a reasonable initial window. For backfill, propose Jan 1 of the current year to today:

health_import_apple_health("/path/to/export.zip")        # Apple Health
health_import_oura(start="2026-01-01", end="2026-05-10") # Oura
health_import_fitbit(start="2026-01-01", end="2026-05-10") # Fitbit (may take 2-5min due to per-day API calls)

Surface the row counts at the end. Confirm with a sample query:

health_recovery_score("2026-05-09")
health_cycle_context("2026-05-09")
health_longevity_panel("2026-05-09")

Step 6: Suggest the ongoing cadence

For Apple Health: re-export from iOS every 1-4 weeks.

For Oura + Fitbit: a daily scheduled task. Suggest creating one via the /schedule skill — pull yesterday's data every morning at 6am. The scheduled task call is:

health_import_oura(start="<yesterday>", end="<yesterday>")
health_import_fitbit(start="<yesterday>", end="<yesterday>")

Each runs in <30 seconds for a single day.

Step 7: Suggest the backfill

If the user wants their existing daily journals enriched with body context retroactively, point them to /backfill-journal-body-context. That skill walks every journal entry this year and appends a body-track section below the original content (verbatim preserved per the journal voice rule).

Voice rules

• Direct, warm, no fluff
• One step at a time — never dump the full wizard in one message
• Copy-paste blocks: indent and code-fence them so the user can copy without losing whitespace
• Match the user's language (Spanish if they Spanish, English if they English)
• If the user is on Windows, never give them macOS commands as the "default"

Multi-vendor merging

If the user has both Apple Watch AND an Oura Ring, the DuckDB schema accepts both. The recovery_score formula will use whichever metric has data for a given day. When both vendors record HRV on the same day, the LAST writer wins (no smart merging in v0.3). v0.4 will add per-source priority preferences.

Graceful failure modes

• Vendor API rate-limited: Fitbit has 150 req/hour. The importer respects the rate by serial single-day calls. If 429 surfaces, suggest a 1-hour wait or chunking the backfill into smaller windows.
• Token expired: Fitbit access tokens expire in 8 hours. If FITBIT_REFRESH_TOKEN + FITBIT_CLIENT_ID + FITBIT_CLIENT_SECRET are set, the client refreshes automatically. If only the access token is set, walk the user back through the OAuth flow.
• No iPhone available: Apple Health requires iOS export. If user has no iPhone, they cannot use the Apple Health path. Route them to Oura (free) or Fitbit.
• Vendor not supported yet: Whoop and direct Garmin support are v0.4. Today's substitute: sync Garmin to Apple Health on iPhone, then export via Apple Health.

Output contract

The wizard does not write any files. It only:

• Calls health_vendor_setup_guide to render instructions
• Asks the user to paste env vars into their shell themselves
• Calls health_vendor_healthcheck and the import tools when they're ready
• Surfaces the row counts + sample queries at the end

No vault writes, no global state changes. The substrate stays clean.