Skip to content

README.md

Latest commit

 

History

History
198 lines (153 loc) · 6.73 KB

README.md

File metadata and controls

198 lines (153 loc) · 6.73 KB
Raw

HealthKit CLI

Query Apple HealthKit data from your iPhone via command line. Works over WiFi and Bluetooth — even when the app is in the background.

Built for Claude Code as an AI health data bridge, but works standalone too.

$ healthkit-cli health summary --days 3

{
  "daily": [
    { "date": "2026-03-21", "steps": 9743, "heart_rate_avg": 58, "sleep_hours": 8.1, ... },
    { "date": "2026-03-20", "steps": 6197, "heart_rate_avg": 52, "sleep_hours": 9.3, ... },
    { "date": "2026-03-19", "steps": 12008, "heart_rate_avg": 63, "sleep_hours": 7.2, ... }
  ]
}

How It Works

iPhone App                          Mac CLI
┌─────────────────────┐            ┌──────────────┐
│ HealthKit reader    │  HTTP/BLE  │ healthkit-cli │
│ HTTP server (:8765) │◄──────────►│              │──► stdout (JSON)
│ BLE peripheral      │            │ Local cache   │
│ Background delivery  │            └──────────────┘
└─────────────────────┘                   │
        ▲                                 ▼
   Apple Watch                     Claude Code / scripts
   syncs health data
  • App in foreground → CLI connects via HTTP (fastest)
  • App in background → CLI connects via Bluetooth LE (BLE peripheral stays alive)
  • Phone unreachable → CLI serves from local cache

Setup

1. Install the iOS app

git clone https://github.com/rakshith48/healthkit-cli.git
cd healthkit-cli/ios-app
xcodegen generate
open PersonalDataHub.xcodeproj

In Xcode:

  • Sign in with your Apple ID (Settings → Accounts)
  • Select your team under Signing & Capabilities
  • Change Bundle Identifier to something unique (e.g., com.yourname.healthkit)
  • Enable HealthKit capability (check "HealthKit" under Signing & Capabilities)
  • Select your iPhone and hit Cmd+R

Grant HealthKit permissions when prompted.

2. Install the CLI

npm install -g healthkit-cli

3. Discover and pair

# Find your phone on the network
healthkit-cli discover

# Pair using the 6-digit code shown in the iOS app
healthkit-cli pair

4. Query your health data

healthkit-cli health steps --days 7
healthkit-cli health heart-rate --days 7
healthkit-cli health sleep --days 7
healthkit-cli health hrv --days 7
healthkit-cli health workouts --days 30
healthkit-cli health summary --days 7
healthkit-cli status

Available Commands

Command Description
healthkit-cli discover Find phone via Bonjour + BLE
healthkit-cli pair Pair with phone using 6-digit code
healthkit-cli status Check phone connectivity
healthkit-cli health summary --days N Daily summary (steps, HR, sleep, calories, distance)
healthkit-cli health steps --days N Step counts per day
healthkit-cli health heart-rate --days N Average heart rate per day (bpm)
healthkit-cli health sleep --days N Sleep duration per day (hours)
healthkit-cli health hrv --days N Heart rate variability per day (ms)
healthkit-cli health spo2 --days N Blood oxygen per day (%)
healthkit-cli health calories --days N Active calories per day (kcal)
healthkit-cli health distance --days N Walking/running distance per day (km)
healthkit-cli health workouts --days N Workouts with distance, HR, pace, splits
healthkit-cli workout queue <file> Push a custom workout spec (JSON) to the iPhone queue
healthkit-cli workout list Show the queue (pending + saved)
healthkit-cli workout clear [id] Remove one queued workout or clear all

Custom Workouts (WorkoutKit)

The workout subcommand pushes a structured workout spec to the iPhone. It appears under the app's Workouts tab. Tap "Preview + Save" and Apple's native preview sheet lets you save the workout directly to the Workout app on your Apple Watch.

Example spec (tempo.json):

{
  "displayName": "Wk 3 Tempo 7km",
  "activity": "running",
  "location": "outdoor",
  "warmup": { "goal": { "distance_km": 1.5 } },
  "blocks": [
    {
      "iterations": 1,
      "steps": [
        {
          "purpose": "work",
          "goal": { "distance_km": 4 },
          "alert": { "type": "pace", "minPace": "5:10", "maxPace": "5:20" }
        }
      ]
    }
  ],
  "cooldown": { "goal": { "distance_km": 1.5 } }
}

Batch form (wrap in { "workouts": [...] }). Supported goals: distance_m, distance_km, time_s, time_min, energy_kcal. Supported alerts: pace (minPace/maxPace), speed_mps, heart_rate (min/max bpm), heart_rate_zone (1-5).

Requires iOS 17+ on the iPhone (WorkoutKit minimum).

Transport fallback: HTTP → BLE

workout queue tries HTTP first (needs the app foregrounded) and falls back to BLE (works when the app is backgrounded; only requires Bluetooth). The BLE path chunks the JSON payload into ~180-byte frames written to a dedicated characteristic, reassembled on the phone, then the same accept/reject ACK is returned over the notification channel. The CLI prints "_source": "http" or "_source": "ble" so you can tell which path succeeded.

Claude Code Integration

Install the /health skill:

healthkit-cli install-skill

Then ask Claude: "How did I sleep this week?" — it will use healthkit-cli automatically.

Data Sources

The CLI reads from Apple HealthKit, which aggregates data from:

  • Apple Watch
  • Ultrahuman Ring
  • Strava
  • Nike Run Club
  • MyFitnessPal
  • Any app that writes to HealthKit

Security

  • All requests require a Bearer token (obtained via 6-digit pairing code)
  • Tokens stored in iOS Keychain + Mac filesystem (0600 permissions)
  • Rate limited (60 req/min)
  • Input validation on all parameters
  • No data leaves your local network

See PRIVACY.md for full details.

Requirements

  • iPhone with iOS 16+
  • Mac with Node.js 18+
  • Python 3.10+ (for BLE — pip install bleak)
  • Xcode (to build the iOS app)
  • Apple Developer account (free works, paid removes 7-day re-sign)

Architecture

iOS App (Swift)

  • HealthKitManager — reads steps, HR, sleep, HRV, SpO2, workouts from HealthKit
  • LocalHTTPServer — Swifter-based HTTP server on port 8765
  • BLEPeripheral — Core Bluetooth peripheral, survives app backgrounding
  • AuthManager — pairing codes + Bearer token validation via Keychain
  • BonjourAdvertiser — mDNS service discovery
  • HealthKit background delivery — auto-caches when Apple Watch syncs new data

CLI (Node.js)

  • 3-tier fallback: HTTP → BLE → local cache
  • Bonjour discovery for zero-config phone finding
  • Bearer token auth
  • All output is JSON

License

MIT