Health.md is a local-first health data platform. This repository is the canonical source for the Apple apps, Android app, standalone CLI, notification-only wake service, practice boundary, and website.
Health.md publishes four instruction bundles from .agents/skills:
| Skill | Use it for |
|---|---|
healthmd-cli |
Consumer CLI and MCP workflows with bounded, user-authorized health access |
healthmd-cli-operator |
Direct iPhone operations and durable-job recovery |
healthmd-cli-development |
CLI, MCP, protocol, and iPhone direct-service development |
healthmd-cli-qa |
Automated and physical-device CLI/MCP validation |
Most users should install only the consumer skill on skills.sh:
npx skills add CodyBontecou/health-md@healthmd-cliA skill supplies agent instructions; it does not install the healthmd binaries, configure MCP, pair a phone, or grant health-data access. See Agent skills and installation for contributor skill commands, local-checkout installation, updates, privacy boundaries, and the publishing contract. Review the CLI preview status before use.
| Path | Product | Toolchain |
|---|---|---|
apps/apple |
iOS, iPadOS, macOS, watchOS, and widgets | Xcode / Swift |
apps/android |
Android app and direct protocol client | Gradle / Kotlin |
apps/cli |
Portable healthmd CLI |
Cargo / Rust |
apps/practice |
Isolated synthetic clinician portal and future clinical boundary | Node.js / Cloudflare Workers |
apps/wake |
Notification-only Direct CLI wake doorbell | TypeScript / Cloudflare Workers |
apps/website |
Product website and documentation | Node.js / Astro |
packages/contracts |
Cross-platform schemas and compatibility fixtures | Language-neutral |
packages/healthmd-core-rust |
Shared export core, UniFFI binding tooling, and direct protocol | Cargo / Rust |
The Health.md Obsidian plugin remains in its own repository and is treated as an external integration.
Each product keeps its native build system and lockfiles. The root Makefile provides convenience commands without replacing component tooling.
make test-contracts
make test-core
make core-bindings
make check-core-bindings
make test-apple
make test-android
make test-cli
make test-practice
make test-wake
make test-websiteSee each component's README and AGENTS.md for platform-specific setup and release instructions.
Health.md keeps Apple and Android unified whenever their operating systems expose semantically compatible capabilities. Shared features should align user outcomes, terminology, settings semantics, public IDs, units, reducers, missingness, provenance, completeness, and automation behavior. Native UI and implementation may follow platform conventions.
When the operating systems differ, Health.md represents that difference explicitly instead of fabricating parity. Unsupported data is omitted/reported unavailable, temporary gaps are tracked as planned with a target, and related-but-different values—such as HealthKit HRV SDNN and Health Connect/WHOOP RMSSD—keep distinct identities.
The governing workflow and definition of done are in docs/architecture/cross-platform-unification-policy.md.
The product-wide feature baseline lives in docs/features/feature-inventory.md: every feature across Apple, Android, CLI, core, contracts, practice, wake, and website surfaces, with source evidence, per-feature documentation status, and the gap list used to manage documentation. Update it when adding a feature. Per-capability Apple↔Android pairings and honest parity classifications live in docs/features/feature-parity.md.
Health.md exports and the direct-device protocol are long-lived compatibility contracts used across Apple, Android, the CLI, website documentation, and external integrations. Contract changes must update fixtures and run every affected consumer's compatibility tests.
See apps/apple/docs/features/export-schema.md for the current Apple export contract and apps/android/docs/export-contract/migration-plan.md for Android compatibility profiles. Normative direct-protocol specifications, interoperability vectors, and the cross-product contract inventory live in packages/contracts. Their shared Rust implementation and canonical metric/profile registry live in packages/healthmd-core-rust; moving deterministic metadata there does not change protocol bytes or public export schemas.
Apple v8, Android frozen v4, and Android analytical v5 remain explicit historical/current profiles. The proposed common successor is healthmd.health_data v9; it unifies truthful shared semantics while preserving independently versioned platform sections for OS-specific data.
Licensing is documented in LICENSES.md. Apple, Android, CLI, Practice, wake, contracts, and shared-core Rust source are AGPL-3.0-only; the website is MIT-licensed.