healthai: a terminal AI chat over your Apple Health export.xml

The export.xml problem healthai is aimed at

Apple Health stores years of measurements, and the only portable copy is an XML export produced from the Health app. That file mixes records from an iPhone, an Apple Watch, a chest strap, and whatever third-party apps sync into Health. The README states plainly that overlapping measurements can exist across those sources, so summing every row double-counts steps, distance, and energy. healthai targets the person who has already generated that export and wants to ask questions of it without uploading it to a service.

The audience named in the README is developers, biohackers, and researchers who want control over the pipeline. That framing matters: the tool assumes you can run a Python package, keep an export file on disk, and decide per metric which device should win. Someone who just wants a step count on a phone is not the target, and the README redirects that reader to applehealthdata.com for a GUI.

How healthai parses, reconciles and answers

The pipeline has three visible stages. First, parsing: the tool reads export.xml and preserves the Record, Workout, and ActivitySummary element types, which is what the README means by high-fidelity export to CSV or JSON. Second, reconciliation: overlapping cumulative intervals are merged rather than added, and the automatic order prefers manually entered Health data, then Apple Watch, then iPhone or iPad, then third-party sources. Units are normalized before aggregation, distance to kilometers, body mass to kilograms, energy to kilocalories, heart rate to BPM. Anything in an unsupported unit is skipped and surfaced by /diagnose rather than silently mislabeled.

Third, the chat layer. The README says the REPL builds query-aware local summaries and includes recent complete rows, so the model is not handed the entire XML. That is a sensible design for context limits, and it also means an answer depends on which rows the summary selected. The README does not document how that selection works, which is the weakest part of the description: if a trend question returns a thin answer, you cannot tell from the documentation whether the data was absent or the summarizer chose poorly.

The repository layout backs up the single-process design: a src/ directory, a run script, an install.sh, a schema.json, and a skills/ folder. The presence of schema.json suggests the export shape is declared somewhere rather than inferred, though the README does not explain it.

Installing healthai and running a first question

The README gives two install paths. The one-liner pipes install.sh into bash, and the alternative is pipx. Both end at the same command, and the first launch runs a setup wizard that asks for a model, an API key if the model needs one, and the path to your export.xml.

curl -fsSL https://raw.githubusercontent.com/krumjahn/applehealth/main/install.sh | bash
healthai

If you prefer to keep the package isolated, the README offers pipx instead:

pipx install healthai
healthai

For a fully local setup with no API key, the README's steps are to install Ollama, pull a model, and pick Ollama in the wizard:

ollama pull llama3.1
ollama pull deepseek-r1

Once you are in the REPL, the README's example questions are plain sentences such as asking for your most active weeks last year, or how sleep correlates with workout intensity. Slash commands handle the deterministic work: /steps, /heartrate, /sleep, /workouts, /weight, /csv, /json, /settings, /diagnose, /setup, /help, /exit. A reasonable first session is /diagnose, then /settings, then a chat question, because the diagnostic output tells you what the parser skipped before you interpret any chart.

Two environment variables are documented for non-interactive use. APPLEHEALTH_UNITS=imperial switches charts, summaries, exported CSVs, and AI analyses to miles and pounds. APPLEHEALTH_SOURCES restricts the run to named sources, for example a single watch, with names matching what the settings screen lists.

APPLEHEALTH_UNITS=imperial APPLEHEALTH_SOURCES="Keith's Apple Watch" healthai

There is also a Docker path. The Dockerfile sets MPLBACKEND=Agg, EXPORT_XML=/export.xml, and OUTPUT_DIR=/out, and it installs requirements-docker.txt, which excludes PyQt6 and py2app.

Where the source reconciliation stops being automatic

The most honest sentence in the README is the admission that export.xml does not include the source order configured in the Health app. That means the automatic preference order is a guess about your setup, not a reading of it. If your preferred tracker is a third-party ring or strap, the default puts it last, behind manually entered data and the Apple Watch. You have to open /settings and set per-metric priority yourself. A user who never touches /settings may get numbers that look plausible and are wrong for their hardware.

The same applies to the source filter. Excluding a noisy app is a one-line change in /settings or an environment variable, and the README frames this as avoiding edits to export.xml. That is convenient, but it also means the exclusion lives in configuration rather than in the data, so two people running the same export.xml can get different totals with no visible trace in the output file.

A second limitation is scope. The README lists Oura, Whoop, and Samsung Ring data as a unified view, but only insofar as those devices sync into Apple Health. healthai reads the Apple export, not the vendor APIs, so anything that never reaches Health is invisible to it.

healthai against a hosted Apple Health dashboard

The obvious alternative is a web dashboard that ingests the same export and renders charts in a browser. The difference is where the parsing and the model call happen. A hosted service does both on its infrastructure, which is why the README's privacy claim is phrased conditionally: nothing goes to a third party unless you choose it. Choosing a cloud model such as GPT-4o, Claude, or Gemini means summaries derived from your data are sent to that provider. Choosing Ollama means the model runs locally and no API key is needed.

That is a real architectural fork, not a marketing line. A dashboard gives you a shareable link and no local setup; healthai gives you a scriptable command and a choice of model endpoint, at the cost of installing Python, managing an export file, and reading diagnostic output before you trust a chart. The README also mentions an OpenClaw skill, which points at the same data being reachable from an agent framework, though the README does not describe that integration in detail.

Licence, maintenance and the cost of upgrading

The pyproject.toml declares license = "MIT" and the README carries an MIT badge, so the package metadata and the documentation agree. The repository's own licence field is listed as unknown in the repository metadata, which is a discrepancy worth resolving by reading the LICENSE file before you vendor the code. MIT is permissive, but the model providers you point healthai at have their own terms, and those terms govern what happens to the summaries sent to them.

The last push to the repository was on 2026-08-06. The latest tagged release in the repository is v1.0.0 from 2025-02-03, while pyproject.toml declares version 1.10.0, so the package version and the release tags do not line up. Anyone pinning a version should pin the PyPI package, not the tag.

Upgrade cost is mostly dependency surface. The declared dependencies include pandas, matplotlib, openai, ollama, anthropic, google-generativeai, litellm, python-dotenv, and prompt_toolkit. The litellm pin excludes two specific versions, 1.82.7 and 1.82.8, which tells you the project has already been bitten by a provider-abstraction release. The Docker requirements drop PyQt6 and py2app, so the container image is lighter than a desktop install.

Editorial conclusion

Adopt healthai if you already have an export.xml and want to query it from a terminal, especially if you plan to run DeepSeek-R1 or Llama 3 through Ollama so nothing leaves the machine. Skip it if you want a phone app or a hosted dashboard, since the README points GUI users to applehealthdata.com instead. Before trusting any number, run /diagnose to see which records were skipped and which units were unsupported, and check /settings to confirm the source priority matches how your devices actually record data.

Frequently asked questions

Official sources

1. Issues
2. krumjahn/applehealth on GitHub
3. Project website
4. README
5. Releases