Cadence is a local-first health context engine designed to bring WHOOP and Apple Health data together into local storage and, through MCP and commands, give Claude usable knowledge about the user's actual current state of sleep, recovery, strain, and workouts, rather than working without information.
Purpose and Core Positioning Cadence's core purpose is to be a local context layer for personal health data. It pulls data from two sources, WHOOP and Apple Health, unifies it into a local SQLite file, and exposes it to Claude for querying. Its goal is not to be a general-purpose health dashboard, but to let an AI assistant know the user's current physical state at the start of a session, and on that basis make more realistic suggestions and correlation analyses.
Data Sources and Privacy Notes WHOOP data comes from WHOOP's own cloud API (via OAuth), which cannot be avoided. But once the pull is complete, the health data exists only on the local machine: a local SQLite file located at ~/.cadence/cadence.db, with permissions 0600 (owner-only access). OAuth tokens are stored in the macOS Keychain, are not written to disk in plaintext, and do not enter the repository. Cadence does not re-upload or share any data with third parties. Apple Health data does not leave the local machine at all - it is imported via local files and involves no network calls. Claude reads the data locally through MCP, which likewise does not cause any data transfer.
How Apple Health and WHOOP Are Connected Apple Health requires no additional setup and is fully local: export all health data from the Health app on iPhone and import it. WHOOP requires a one-time OAuth setup: register a personal app at developer.whoop.com, fill in the privacy policy link, redirect URL, and check the six data scopes (read:recovery, read:cycles, read:sleep, read:workout, read:profile, read:body_measurement). Leave Webhooks blank, because Cadence uses a pull model (cadence sync). Under developer statusThe app can be used immediately by up to 10 WHOOP accounts; personal use requires no approval. After that, export the client ID and secret (shown only once), run cadence auth to complete authorization, and the token will be stored in Keychain. From then on, cadence sync will work automatically and will automatically handle refresh token rotation.
MCP service Cadence provides an MCP service, enabling Claude to query local data in real time rather than only reading briefings. By using claude mcp add cadence -- cadence mcp or an equivalent stdio-server configuration, the Claude client can be pointed at this service.
Health-aware AI sessions (v0.2.0) cadence hook outputs the SessionStart hook payload for Claude Code, so that the first Claude session of each day already knows the user's physiological state when it opens—last night's sleep, today's recovery, recent stress—and includes a line of adaptive prompting when the values need attention (for example, suggesting lightweight work rather than marathon-style building when recovery is low). The second session of each day is silent by default to avoid unnecessary noise. The hook does not block the session, makes no network calls, only reads local SQLite, and on any failure path chooses silence rather than interrupting session startup.
Personal baselines and anomaly detection (v0.3.0) All thresholds are personalized, not population norms. Cadence establishes true 30-day rolling means/standard deviations for each metric (recovery score, HRV, resting heart rate, respiratory rate, sleep duration/efficiency), and only flags when today's value shows a true statistical deviation relative to the individual's normal level (|z| >= 1.5). An important guardrail is that a metric is silently omitted until more than 14 days of real history have accumulated, rather than being displayed with a misleadingly small sample size. Anomalies are surfaced in three ways: inline in the briefing/session hook; if a new severe deviation (|z| >= 2.5) appears after the day's first session, the hook triggers a reminder again; and unattended sync tasks send macOS notifications for severe levels. The weekly report is generated by cadence digest to a configurable directory and can optionally be committed to a notes/journal repository; email delivery is intentionally not integrated.
A mirror of body, code, and AI usage (v0.4.0) This is Cadence The more distinctive part: it is the first tool to put git commit history, Claude usage, and physiological data into the same local correlation layer. All correlations are simple two-group mean comparisons based on the user's own history, without regression or significance-testing packaging. For groups with fewer than 14 days of real overlapping data, Cadence refuses to report any results and clearly labels them as "observational, not causal." MCP tools include get_developer_rhythm() and get_body_code_correlations().
On-device narration (v0.5.0) cadence digest --narrate can turn a structured weekly report into 2-3 paragraphs of conversational text, generated entirely on-device via langchain-apple-foundation-models, with zero cloud services and zero cost. This feature is an optional install (pip install cadence[narrate]), and Cadence itself works without depending on Apple Intelligence. The documentation honestly records the hallucination that occurred on first generation (the model claimed the data was insufficient, while the baseline in the input was actually already sufficient), and explains that the fix is to place the narration on top of the deterministic structured weekly report, rather than replacing it.
Data processing and engineering details The two sources are normalized into a unified local SQLite schema (sleep, recovery, workouts, daily_metrics), with each row labeled with its source. When the two sources cover the same event, Cadence does not silently merge them into a false "canonical" record, but instead explicitly chooses and explains: sleep stages are prioritized from WHOOP, recovery/stress is provided only by WHOOP; steps and other daily activity are provided by Apple Health. Apple Health export files can be 200MB-1GB or more of XML, and the code uses iterparse for streaming processing and actively evicts already-processed elements to control memory. Sleep records are merged into real sessions by continuous time periods. The WHOOP refresh token rotates on every use, and the code immediately persists the new token before returning. The documentation also records several real bugs (boundary overlap in trend calculation, test isolation issues, partial-day bias, WHOOP date parameters only accepting full ISO8601, etc.) and their fixes.
Applicable scenarios and limitations Cadence is suitable for users who want AI assistants such as Claude to obtain personal health context locallyand with controllable privacy, and is especially suitable for people who care about the correlation between recovery, sleep, and work/coding rhythm. It currently relies on the WHOOP cloud API to obtain WHOOP data, Apple Health requires manual export and import, and token storage relies on the macOS Keychain. The narration feature requires Apple Intelligence and is optional. Correlation analysis will explicitly output no results when the amount of data is insufficient.
