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, stacks, 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 (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):
   server.ts

   Copy

   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 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 a configurable directory and can optionally commit it to a notes/journal repo. Email delivery is intentionally not wired up -- see digest.py's module docstring for the reasoning.

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
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.

The honesty guardrail in practice: the commit-hour histogram is available immediately (a pure histogram has no threshold to clear), but the deeper correlations (late-night coding vs. next-morning recovery, short sleep vs. commit output, heavy Claude usage vs. next-day recovery) return nothing until there are 14+ days of real overlapping data per group -- on a fresh setup they correctly report nothing rather than manufacture a "finding" from 2-3 data points, and start reporting real numbers only as the logs accumulate past that threshold.

MCP tools: get_developer_rhythm(), get_body_code_correlations().

On-device narration (v0.5.0)

cadence digest --narrate turns the structured weekly digest into 2-3 plain-spoken paragraphs, generated entirely on-device via langchain-apple-foundation-models. 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 committing anything