cadence

# cadence A local-first health-context engine. Pulls WHOOP and Apple Health into one local store, and gives Claude real, current knowledge of how you're actually doing -- sleep, recovery, strain, workouts -- instead of working blind.  ## The honest privacy story Unlike the rest of this portfolio ([lantern](https://github.com/rajanshxrma/lantern), [stacks](https://github.com/rajanshxrma/stacks), [orchard](https://github.com/rajanshxrma/orchard)), cadence can't claim "nothing leaves the machine" -- WHOOP data necessarily comes from WHOOP's own cloud API over OAuth, there's no way around that. What's real and true instead: **once pulled, your health data lives only on this machine** (a local SQLite file at `~/.cadence/cadence.db`, permissioned `0600`, owner-only), your OAuth tokens live in the macOS Keychain (never on disk in plaintext, never in this repo), and cadence never re-uploads or re-shares anything to a third party. Apple Health data never leaves the machine at all -- it's a local file import, no network call involved. Claude reads your data locally via MCP; nothing about that transmits it anywhere else either. ## Install ``` pip install -e . ``` **Apple Health (no setup, fully local):** ``` cadence import-apple-health ~/Downloads/export.zip cadence brief ``` (Export from iPhone: Health app -> profile icon -> Export All Health Data.) **WHOOP (one-time OAuth setup, see below):** ``` cadence auth # opens a browser once, stores tokens in Keychain cadence sync # pulls the last 30 days of recovery/sleep/workouts cadence brief ``` **MCP server** (so Claude can query this live instead of just reading the brief): ``` cadence mcp ``` Point your Claude client at it (`claude mcp add cadence -- cadence mcp`, or the equivalent stdio-server config for your client). ## WHOOP setup (one-time) 1. Register a personal app at [developer.whoop.com](https://developer.whoop.com/) (sign in with your normal WHOOP account, create a Team if prompted, then create an App). Fill in: - **Privacy Policy**: a real link is required -- `https://github.com/<your-fork>/cadence#the-honest-privacy-story` (this section) is a reasonable choice for a personal-use app. - **Redirect URL**: must exactly match `cadence.auth.REDIRECT_URI` (`https://github.com/rajanshxrma/cadence` by default). WHOOP's own form only accepts `https://` or a custom URL scheme -- a plain `http://localhost` redirect is rejected, which is why `cadence auth` uses a copy-paste flow instead of a local callback server (see `auth.py`'s module docstring). - **Scopes**: check all six data scopes (`read:recovery`, `read:cycles`, `read:sleep`, `read:workout`, `read:profile`, `read:body_measurement`). There's no `offline` checkbox on the form -- that scope is requested dynamically in the actual authorization request, not a per-app setting. - **Webhooks**: leave empty -- cadence is pull-based (`cadence sync`), no webhook receiver. - Apps work immediately for up to 10 WHOOP accounts in dev status -- no approval needed for personal use. 2. Export your credentials (shown once on the app's page after creation -- copy both immediately): ``` export CADENCE_WHOOP_CLIENT_ID="..." export CADENCE_WHOOP_CLIENT_SECRET="..." ``` 3. Run `cadence auth`. It opens your browser; after you approve, WHOOP redirects there with a code in the URL -- copy the full address-bar URL and paste it back into the terminal when prompted. Tokens land in Keychain. `cadence sync` after that just works -- refresh happens automatically (WHOOP rotates refresh tokens on every use; cadence persists the new one each time, per their API's requirement). Client id/secret are read from environment variables only -- never written to disk, never committed. `keyring` (the library used for token storage) needs an OS credential store; on macOS that's Keychain, no extra setup. ## Health-aware AI sessions (v0.2.0) The piece that makes this more than a data viewer: `cadence hook` emits a [Claude Code SessionStart hook](https://docs.anthropic.com) payload, so the **first Claude session of each day opens already knowing your physiological state** -- last night's sleep, today's recovery, recent strain -- plus a one-line adaptive hint when the numbers warrant one (low recovery: "favor lighter work over marathon builds"; short sleep: flagged; data gone stale: a re-sync nudge instead of silent death). Second session of the day: silent, by design -- a hook that talks every session is noise. ``` cadence hook # prints the SessionStart JSON (or nothing -- silence is a feature) cadence sync --quiet # unattended mode for a launchd/cron job; macOS-notifies if re-auth is ever needed cadence auth --store-client # one-time: persist client creds to Keychain so unattended sync needs no env vars ``` Wire-up: a 15-line shim script in your hooks config calls `cadence hook`; a launchd job runs `cadence sync --quiet` twice daily. The hook never blocks a session -- no network calls (local SQLite reads only), and every failure path chooses silence over a broken session startup. ## Personal baselines and anomaly detection (v0.3.0) Every threshold below is PERSONAL, never a population norm -- cadence builds a real 30-day rolling mean/std of your own history per metric (recovery score, HRV, resting heart rate, respiratory rate, sleep duration/efficiency) and flags today's value only when it's a real statistical deviation (|z| >= 1.5) from *your* normal, not some generic chart's idea of normal. **The honesty guardrail that matters most here:** a metric is silently omitted from baselines (not shown with a misleading small n) until there are 14+ days of real history behind it. An anomaly built on 3 data points is noise dressed up as insight -- this project would rather say nothing than say something confidently wrong. ``` cadence baseline # prints current baselines + any deviations today ``` Anomalies surface three ways, each calibrated to how urgent they are: - **In `brief`/the session hook** -- inline, every time they exist. - **A focused re-alert mid-day** -- if a NEW serious deviation (|z| >= 2.5) appears after the day's first session already happened (e.g. an 8pm sync lands something the 8am one didn't have), the hook fires again just for that -- a real new signal outranks the once-daily quota. Already-seen deviations never re-fire the same day. - **A macOS notification from the unattended sync job** for the serious tier specifically -- the one thing worth interrupting silence for. **Weekly digest:** `cadence digest` writes a dated summary to `~/ai-brain/digests/cadence/` and commits+pushes it (ai-brain is private, so this auto-pushes with no prompt, per the same convention as this project's other digest routines). Email delivery is intentionally NOT wired up yet -- see `digest.py`'s module docstring for why (a parallel routine already flagged digest-email fatigue; adding a 7th one without that conversation happening first would be the wrong call). ## The mirror: body, code, and AI usage in one place (v0.4.0) This is the piece that doesn't exist anywhere else. A few WHOOP-MCP servers exist publicly; a health tool alone isn't novel. What's actually new: cadence is the first place your **git commit history**, your **Claude usage**, and your **physiological data** live in one local correlation layer -- all three time-series were already sitting on the same machine, just never joined. ``` cadence config add-repo ~/Downloads/your-project # point it at your own repos -- fully generic, not hardcoded to mine cadence mirror # commit-hour rhythm + observational correlations ``` **The honesty discipline that makes this real rather than a toy:** every correlation is a simple two-group mean comparison on YOUR OWN history -- no regression, no significance testing dressed up as more than it is -- and it **refuses to report anything with fewer than 14 days of real overlapping data per group**, full stop. Every result that does print carries an explicit methodology note (exactly how the two variables were date-joined, stated plainly as "observational, not causal"). Silence is the honest answer below that threshold, never a confident-sounding number built on noise. **What this actually found, live, on day one (2026-07-10):** across the last 90 days, **56% of commits across 11 real repos land between midnight and 6am** -- a real, immediately-available rhythm signal, no threshold to clear for a pure histogram. The deeper correlations (late-night coding vs. next-morning recovery, short sleep vs. commit output, heavy Claude usage vs. next-day recovery) correctly returned **nothing** on this same first run -- not a bug, verified: real commit activity only spans 7 distinct calendar days in that window, and `usage-history.jsonl` had only just started logging. The honesty guardrail did exactly its job: refused to manufacture a "finding" from 2-3 data points. As both logs accumulate past the 14-day threshold, the same commands will start reporting real numbers -- exactly the discipline this project is built around, demonstrated by its own first real run, not just claimed in a docstring. MCP tools: `get_developer_rhythm()`, `get_body_code_correlations()`. ## On-device narration (v0.5.0) -- the portfolio loop closes `cadence digest --narrate` turns the structured weekly digest into 2-3 plain-spoken paragraphs, generated entirely on-device via [langchain-apple-foundation-models](https://github.com/rajanshxrma/langchain-apple-foundation-models) -- the very first repo in this whole body of work, now the insight engine for the last one. Zero cloud, zero cost, `pip install cadence[narrate]` (optional -- cadence never depends on Apple Intelligence to work). ``` cadence digest --narrate --no-commit # try it without touching ai-brain ``` **A real hallucination, found and fixed live, not glossed over:** the first working prompt produced a real run where the digest's own baseline section plainly showed real numbers (recovery score 72.7±21.3%, n=23) and the model still wrote "there isn't enough data to compare your recovery score to your 30-day baseline" -- flatly contradicting its own input. Same bug class already documented in [lantern](https://github.com/rajanshxrma/lantern)'s README. Fixed by making the instructions explicit about what "not enough data" is allowed to mean (only when that literal phrase appears in the input); verified across 3 consecutive real generations post-fix with zero hallucinated claims and every number reproduced verbatim. Not proof it can never recur -- prompting alone never fully eliminates hallucination -- which is exactly why the narration is inserted ABOVE the deterministic structured digest, never replacing it: the real numbers are always sitting right there to cross-check against. ## How it works | | WHOOP | Apple Health | |---|---|---| | Where the data comes from | Cloud API, OAuth 2.0 | Local `export.zip` (manual export from the Health app) | | What it uniquely has | Recovery score, HRV (RMSSD), strain, sleep performance/efficiency | Steps, active/basal energy, exercise minutes, distance, HRV (SDNN), workout GPS-adjacent detail | | Network calls | Yes, to pull data (`cadence sync`) | None -- pure local file parse | | Sync model | Pull-based, run `cadence sync` whenever | One-time import per export (re-import to refresh) | Both sources get normalized into one local SQLite schema (`sleep`, `recovery`, `workouts`, `daily_metrics`), each row tagged with its `source`. When both sources cover the same real-world event (e.g. the same night's sleep), cadence doesn't silently merge them into a fake "canonical" record -- it picks explicitly and says so: WHOOP wins for sleep staging and is the *only* source for recovery/strain (Apple Health has no equivalent computed score); Apple Health is the source for step count and other daily activity WHOOP's API doesn't expose. ## Real engineering challenges (found and handled, not glossed over) 1. **The Apple Health export can be 200MB-1GB+ of XML.** `apple_health.py` streams it with `xml.etree.ElementTree.iterparse` and actively evicts every processed element from the parse tree -- `elem.clear()` alone isn't enough (a well-known stdlib gotcha: the element still sits in its parent's children list). Verified, not just claimed: a 300k-record/48MB synthetic file grew peak RSS by ~19MB with full eviction vs ~27MB with `elem.clear()` alone -- a real, measurable difference that gets far more pronounced at real-export scale (millions of records). 2. **Apple Health emits sleep as dozens of small per-stage records, not one row per night.** `_group_sleep_sessions()` reduces them into real sessions by contiguous time (a >2h gap starts a new night), summing per-stage seconds -- tested against both a gap-split case and a same-night merge case. 3. **WHOOP rotates refresh tokens on every use** -- the old one is invalidated the instant a new one is issued. `auth.py`'s refresh path persists the new refresh token immediately, before returning; dropping that step "to simplify" would break sync after the very next token rotation. 4. **A real off-by-one bug in the trend calculation**, caught by its own test: comparing "this week" vs "last week" with naive inclusive date bounds put the shared boundary day in *both* windows, inflating the recent average (measured: 8625 instead of the correct 9000 in a 9000-vs-6000 synthetic scenario). Fixed by making the two windows properly disjoint. 5. **A real test-isolation bug, caught by its own test:** `store.connect()`'s default argument originally bound `DEFAULT_DB_PATH` at function-*definition* time, so reassigning `store.DEFAULT_DB_PATH` in a test (to isolate it from the real `~/.cadence/cadence.db`) silently had no effect -- an early test run actually wrote real synthetic test rows into the real local store on the dev machine before this was caught and fixed. `tests/test_tools.py::test_tools_never_touch_real_default_db_path` now guards against a regression. 6. **A partial-day bias in the trend math, found by the first run against real data -- the kind of bug synthetic tests can't catch.** The week-over-week trend originally included *today* in the recent window; a `cadence brief` run in the early morning counted that morning's few hundred steps as a full day, and the first live report claimed steps were "down 56% vs the week before" -- partly an artifact of when the command happened to run, not real behavior. A health brief that's subtly wrong depending on the time of day is worse than no brief. Both comparison windows now cover complete days only, ending at yesterday, with a regression test pinning today's exclusion. 7. **WHOOP's `start`/`end` params silently 404 on a bare date.** Found live: `?start=2026-06-10` returns a plain 404 (not a validation error), while the identical request with `?start=2026-06-10T00:00:00.000Z` returns 200 with data. Full ISO8601 datetimes only -- now enforced by `_iso_datetime()` with its own regression test. 8. **The same lexicographic-date-comparison bug, twice, in two different modules.** `sleep`/`workouts` rows store full ISO timestamps ("2026-07-10T03:00:00Z"), which sort *after* a bare date string ("2026-07-10") -- so a bare `date.today().isoformat()` upper bound silently excludes today's own rows. This was already found and fixed once in `apple_health.py`'s tests; it recurred in `digest.py` (a genuinely new bug, not a regression of the first) because the fix pattern (`brief.py`'s `+1 day` buffer) wasn't applied to the new module by default. Now consistent everywhere query bounds are built. Worth remembering: a fixed bug in one module doesn't protect a sibling module written later -- the pattern has to be applied deliberately each time, not assumed. 9. **A real correlation bug, caught by its own test before it ever touched real data.** `late_night_cost()` originally iterated over commit-days to build its two comparison groups -- which meant days with ZERO commits (exactly the "no late-night commit" group it needed) were silently excluded entirely, since they never appear in commit data at all. Fixed by iterating over health-outcome days instead and defaulting missing commit data to zero, the same pattern `sleep_to_output()` already used correctly. Caught by a real end-to-end test (a synthetic repo + synthetic recovery data) before this ever ran against a real account -- had it shipped as written, real correlation results would have been silently computed from a biased, commits-only subset instead of the true comparison. ## Limitations, stated honestly - **WHOOP field mapping is live-verified against a real account** (2026-07-10: a real 30-day sync pulled 23 recovery, 25 sleep, and 36 workout records, and the brief rendered real numbers correctly). Two real integration bugs surfaced during that first live run and are fixed with regression tests -- see challenges #6 and #7 above. - **Apple Health parsing covers a curated allowlist of metric types** (steps, energy, distance, exercise minutes, resting heart rate, HRV-SDNN, respiratory rate, VO2max) and the classic attribute-based `<Workout>` schema -- not every HealthKit type Apple can export, and units are assumed to be Apple's standard emitted units except where explicitly converted. - **Apple Health workouts have no stable id in the export format** -- cadence synthesizes one from (start time, activity type), an extremely-low-collision approximation, not a real Apple-issued identifier. - Apple Health's own HRV measure (SDNN) and WHOOP's (RMSSD) are genuinely different statistics -- cadence keeps them in separate fields rather than pretending they're interchangeable. ## Development ``` pip install -e ".[dev]" pytest -v ``` Real, no-mock tests throughout: a synthetic (non-personal) Apple Health export fixture exercised end-to-end, WHOOP normalization against synthetic-but-realistically-shaped JSON (no live token needed), and every MCP tool invoked through the actual `mcp` protocol layer, not just imported and called directly. MIT.