health-data

# Purpose The `health-data` skill provides deterministic helpers to read and summarize Apple Health backup exports. The bundled `health-data.sh` script understands the zipped export Apple Health lets you download and can also work against the unzipped folder with `export.xml`. Use this skill when you need to inspect record types, compute totals (steps, distance, sleep), or extract JSON for further analysis without sending the sensitive XML off-box. # Safety - Apple Health exports contain PII/PHI (biometric, sleep, location, heart-rate, etc.). Never publish the raw XML, upload the zip, or paste any values into third-party services without explicit consent and legal review. - The script only reads data locally and cleans up its temporary extraction. Keep the exported zip/folder on disk-free space you control and delete it when the analysis is done. - Running `summary` or `export-json` now emits a runtime PHI warning banner to stderr; treat every derived artifact as PHI/PII unless you have an explicit legal/research justification. - The `export-json` command streams records instead of slurping them, warns on stderr after emitting 100,000 records without `--limit`, and supports `--out <file>` so you can save the JSON to a file created with 600 permissions instead of dumping to stdout. - Request explicit confirmation before writing any derived health reports if the values are later shared with others (medical, legal, or employment contexts). # Quick start ```bash # List which HealthKit record types appear most often health-data/health-data.sh list-types ~/Downloads/export.zip # Summarize range, totals, and common sources health-data/health-data.sh summary ~/Downloads/export.zip # Get JSON records for steps (use jq to filter further) health-data/health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/Downloads/export.zip --limit 20 # Or save to a restricted file (600-permission) instead of stdout health-data/health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/Downloads/export.zip --limit 20 --out ~/Documents/steps.json ``` # Commands ## list-types <export-path> Prints every `<Record type="...">` identifier in the export, sorted by frequency. Use this to understand which categories (steps, workouts, heart rate, etc.) are available before you dig into payloads. ## summary <export-path> Reports: - total record count and date coverage - step count and walking/running distance sums (meters by default) - counts of sleep analysis categories (asleep/in-bed) - top five data sources by record volume This command relies on `xmlstarlet` to query the XML so it stays fast even on large exports. ## export-json <record-type> <export-path> [--limit N] [--out <file>] Pulls the requested record type into JSON so you can pipe it to `jq`, Python, or other tools. The command emits a runtime PHI warning banner on stderr, streams records instead of slurping them, warns after 100,000 emitted records when `--limit` is omitted, and supports `--out <file>` to save the JSON to a file created with 600 permissions. Supply `--limit` to avoid overwhelming the reader (default: unlimited). Examples: ```bash health-data/health-data.sh export-json HKCategoryTypeIdentifierSleepAnalysis ~/Downloads/export.zip --limit 5 ``` ```bash health-data/health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/Downloads/export.zip --limit 20 --out ~/Documents/step-records.json ``` # Advanced filtering Because the output from `export-json` is valid JSON, use `jq` for additional insights: ```bash health-data/health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/Downloads/export.zip --limit 50 \ | jq '[.[] | {value, startDate}]' ``` Combine `jq` selectors (like `map(select(.unit == "count"))`) to focus on specific fields without writing additional parsing logic. # Examples - "What record types did my Health export include?" → `health-data.sh list-types ~/path/to/export.zip` - "Show me step totals and sleep breakdown for my export" → `health-data.sh summary ~/path/to/export.zip` - "I want the raw step records for the last week" → `health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/path/to/export.zip --limit 100` and pipe through `jq '.[].startDate | select(startswith("2026-03"))'` - "Save a slice of the export to a local file" → `health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/path/to/export.zip --limit 50 --out ~/Documents/step-records.json` # Troubleshooting - **`no such file or directory`**: Ensure the export path points to either apple_health_export/export.xml or the zipped export produced by Apple Health. - **`zip ... does not contain export.xml`**: Re-export from the Health app—sometimes partial exports omit the XML if interrupted. - **Missing dependencies**: Install `xmlstarlet`, `jq`, and `unzip` via Homebrew (`brew install xmlstarlet jq unzip`).