healthsync

Parse Apple Health exports into a local SQLite database — queryable by AI agents, the CLI, or directly via SQL.

The primary motivation is to make your Apple Health data accessible to AI coding agents. Run healthsync skills install to give Claude Code, Codex CLI, or OpenClaw the schema, CLI reference, and SQL examples it needs to answer questions about your health data in conversation.

Docs: healthsync.sidv.dev

Install

Homebrew

brew tap BRO3886/tap
brew install healthsync

Or install via the install script:

curl -fsSL https://healthsync.sidv.dev/install | bash

Or install with Go:

go install github.com/BRO3886/healthsync@latest

Or download a pre-built binary from GitHub Releases (macOS and Linux, arm64 and amd64).

Or build from source (requires Go 1.24+):

git clone git@github.com:BRO3886/healthsync.git
cd healthsync
go build -o healthsync .

Usage

Parse an export

Export your Apple Health data from the Health app on iPhone (Settings > Health > Export All Health Data). Then:

healthsync parse export.zip
healthsync parse export.zip -v  # verbose logging

Accepts .zip or raw .xml files. Inside a zip, the HealthKit XML is identified by content, so exports from non-English devices (e.g. 导出.xml on Chinese) work without renaming.

Query data

healthsync query heart-rate --limit 10
healthsync query steps --from 2024-01-01 --to 2024-06-30
healthsync query workouts --format json
healthsync query spo2 --format csv
healthsync query resting-heart-rate --limit 30
healthsync query blood-pressure --limit 20
healthsync query body-mass --limit 30

Output formats: table (default), json, csv

Use --total with steps, active-energy, basal-energy, or sleep for deduplicated daily (or nightly) totals:

healthsync query steps --total --from 2024-01-01
healthsync query active-energy --total --from 2024-01-01
healthsync query sleep --total --from 2024-01-01   # nightly sleep duration, hours

AI agent skills

Install the healthsync skill to teach your AI coding agent how to query your health data:

healthsync skills install

This writes the database schema, CLI reference, and SQL query examples to ~/.claude/skills/healthsync/ (Claude Code), ~/.agents/skills/healthsync/ (Codex CLI), or ~/.openclaw/skills/healthsync/ (OpenClaw). The agent picks it up automatically on the next session start and can then answer questions like "What was my average heart rate last week?" by running queries against your local database.

# Check installation status
healthsync skills status

# Uninstall
healthsync skills uninstall --agent claude

HTTP server

Start a server for receiving uploads (e.g. from iPhone Shortcuts over Tailscale):

healthsync server --port 8080 --host 0.0.0.0

Endpoints:

• POST /api/upload — upload a .zip or .xml file (multipart form, field: file). Returns 202 Accepted and parses asynchronously.
• GET /api/upload/status — poll parse job progress.
• GET /api/health/{table}?from=&to=&limit= — query health data as JSON.

# Upload
curl -F "file=@export.zip" http://localhost:8080/api/upload

# Check progress
curl http://localhost:8080/api/upload/status

# Query
curl "http://localhost:8080/api/health/heart-rate?limit=5"

Metrics

Currently parsed

Cardiac / Vitals

Activity / Energy

Body

Mobility / Walking

Running

Sleep / Mindfulness / Other

Not yet parsed

Design

• Streaming XML parser — constant memory (~10MB) for 950MB+ files using xml.Decoder token-based parsing
• Dedup — INSERT OR IGNORE with UNIQUE constraints for idempotent re-imports
• Batch inserts — 1000 rows per transaction for performance
• Async uploads — HTTP server parses in background, poll /api/upload/status for progress
• Pure Go SQLite — uses modernc.org/sqlite, no CGO required
• Agent skills — embedded skill files (go:embed) installed via healthsync skills install

Database is stored at ~/.healthsync/healthsync.db by default (override with --db).

License

MIT