vitalog 0.2.3

A CLI tool for managing personal health data from Apple Health and SleepCycle. Load data into a local DuckDB database, generate AI-powered health narratives with Claude, and build interactive static HTML dashboards — no database server required.

Features

• vitalog load — Extract Apple Health XML exports and SleepCycle CSV data into a local DuckDB database
• vitalog narrative — Generate AI-written health journal entries using Claude, with trend analysis and period-over-period comparisons
• vitalog dashboard — Build self-contained static HTML dashboards with D3.js charts, Leaflet workout route maps, dark mode, and interactive tooltips

Installation

pip install vitalog

Or install from source with uv:

git clone https://github.com/geocoug/vitalog.git
cd vitalog
uv sync --all-extras

Usage

Load data

# Load an Apple Health export (ZIP from iPhone → Health → Export)
vitalog load apple --file data/export.zip

# Load SleepCycle app data (CSV export)
vitalog load sleep --file data/sleepdata.csv

# Load both at once
vitalog load all --apple data/export.zip --sleep data/sleepdata.csv

# Apple Health only (SleepCycle is optional)
vitalog load all --apple data/export.zip

Both commands write to vitalog.duckdb in the current directory by default. Override with --db path/to/file.duckdb.

Generate a health narrative

# Last week summary
vitalog narrative --period last-week

# Custom date range, saved to file
vitalog narrative --start 2025-01-01 --end 2025-03-31 --output q1-narrative.md

# Ask a specific question about your health data
vitalog narrative --question "How has my sleep quality changed?"

# Question with a specific time period
vitalog narrative --period last-month -q "Am I exercising enough?"

Set your profile (optional)

# Provide demographics for personalized health context in narratives
vitalog profile --age 35 --weight 175 --height 70 --sex male

# View current profile
vitalog profile --show

Demographics are stored in the DuckDB database and used to contextualize metrics in narratives (e.g., age-appropriate resting HR norms, BMI, VO2Max percentiles).

Generate a health narrative

Requires ANTHROPIC_API_KEY set in your environment or .env file. Optionally set ANTHROPIC_MODEL to choose a specific Claude model (defaults to claude-sonnet-4-20250514).

Build a dashboard

# Last year dashboard (opens in browser)
vitalog dashboard --period last-year

# Custom range, no auto-open
vitalog dashboard --start 2024-01-01 --end 2024-12-31 --output 2024.html --no-open

Generates a self-contained HTML file with 20+ interactive charts across 6 tabs: Overview, Vitals, Sleep, Training, Activity, and Routes.

Data Sources

Apple Health Export

How to export: iPhone → Health app → profile icon → Export All Health Data → save ZIP file.

Expected format: A ZIP archive containing:

• apple_health_export/export.xml — All health records, workouts, and activity summaries
• apple_health_export/workout-routes/*.gpx — GPS tracks for outdoor workouts

What gets extracted:

SleepCycle CSV

How to export: SleepCycle app → Profile → More → Database → Export Database → save CSV file.

Expected format: Semicolon-delimited CSV (;) with headers including:

Start;End;Sleep Quality;Regularity;Deep (seconds);Light (seconds);Dream (seconds);
Awake (seconds);Heart rate (bpm);Steps;...

What gets extracted: Sleep duration, quality percentage, stage breakdown (deep/light/REM/awake), heart rate, environmental data (air pressure, temperature, weather), and snore time.

What Gets Produced

DuckDB Database

A local vitalog.duckdb file with staging tables and analytical views:

Plus analytical views: daily_steps, daily_heart_rate, daily_resting_hr, daily_summary, workout_summary, sleep_combined.

Dashboard

A single self-contained HTML file (~700KB) with:

• 6 tabbed sections with 20+ interactive charts built with D3.js
• Summary cards with sparkline trends
• Personal records section
• Monthly summary table with conditional formatting
• Workout route maps with GPS tracks built with Leaflet
• Dark/light mode toggle
• Print-friendly CSS

Narrative

A markdown document with a 3-5 paragraph AI-generated health journal entry covering steps, heart rate, sleep, workouts, and activity rings — with trend analysis vs. the prior equivalent period.

Development

# Clone and install
git clone https://github.com/geocoug/vitalog.git
cd vitalog
uv sync --all-extras

# Run tests
just test

# Lint + format
just lint

# Run pre-commit hooks
just pre-commit

# See all available recipes
just

License

GNU General Public License v3.0