VitalChronicle

Your health history, privately understood.

VitalChronicle is a local-first desktop application for downloading, storing, exploring, and exporting personal data made available through the Google Health API. It combines adaptive visualisations with optional analysis performed by a local Ollama model. Health records stay on the computer unless the user explicitly exports them.

VitalChronicle is and will remain free and open-source software. If it is useful to you, a voluntary contribution through Buy Me a Coffee helps keep development active and the downloadable packages available.

Another valuable way to support this open-source project is to help translate VitalChronicle on Weblate. No programming experience is required.

VitalChronicle is an independent project. It is not affiliated with, endorsed by, or supported by Google. It is an exploratory wellness-data tool, not a medical device and not a replacement for professional medical advice.

Download

Download the latest VitalChronicle release for Linux, Windows, or macOS

The exact current version is always shown by the release badge at the top of this README and by GitHub on the linked release page. These links update automatically whenever a new version is published.

Windows and macOS packages are not signed with paid platform certificates. Download only from the official release page and verify SHA256SUMS.txt. The Linux AppImage is attested through GitHub Actions and includes a detached Sigstore bundle.

Interface

Screenshots are generated from the real application using synthetic demonstration data. No personal health record or credential is included in this repository.

Seven-day overview

The overview distinguishes cumulative metrics from physiological measurements. Steps, sleep, and active-zone minutes use completion bars against the preceding seven-day average. Heart rate and other vital measurements use neutral above/below-baseline comparisons, compact trend plots, and a one-standard-deviation reference band.

Data explorer

Charts adapt to the selected record: daily bars for steps and energy, point clouds for dense measurements, stacked bars for sleep stages and heart-rate zones, and readable vertical ranges for noisy measurements. Panning and zooming operate on time.

Private local AI

The AI tab is a control centre; conversations open in a larger, resizable window with local thread history, follow-up questions, stop/regenerate controls, Markdown export, and an evidence drawer. Thinking and the final answer share one assistant area. Each conversation pins its data snapshot and visibly offers a refresh when newer local data become available.

Before Ollama receives anything, deterministic Python preparation calculates personal 7/28/90-day baselines, matched recent-versus-previous periods, robust anomalies, trends, weekly patterns, coverage gaps, sleep-stage and workout comparisons, plus same-day and one-day-lagged associations. Evidence is ranked so the model can synthesize sustained, multi-metric patterns instead of merely reporting that one day differs from another. Incomplete cumulative totals are compared only with previous days at the same local time.

AI memory and token settings

The user enters installed RAM and receives a model-aware token recommendation. The value remains editable and is limited only by the physical context reported by Ollama.

Main capabilities

• seven-step beginner-friendly Google Cloud and OAuth configuration inside the application, including direct links, completion checks, JSON validation, and browser fallbacks;
• incremental synchronisation that downloads only missing intervals;
• silent refresh at startup and every ten minutes while the application is open;
• per-category error isolation, warnings, pagination, and resumable local coverage;
• local SQLite archive with CSV, JSON, and complete ZIP export;
• purpose-specific plots for activity, sleep, heart, oxygen, temperature, nutrition, workouts, sedentary time, body measurements, and other available categories;
• readable time windows and robust vertical scales for dense measurements;
• seven-day personal baselines and transparent statistical bands;
• deterministic AI preparation with matched periods, multi-horizon personal baselines, robust anomaly detection, data-quality scoring, and cautious cross-metric associations;
• persistent local AI conversations in a separate resizable window, including follow-up questions, pinned/updatable data snapshots, visible thinking, evidence, export, and stop;
• two-pass complete-history synthesis through local Qwen/Ollama, with NVIDIA 16 GB and CPU-only 32 GB profiles;
• model-update notifications and model-context-aware token recommendations;
• automatic in-app checks for new VitalChronicle releases, with a manual Help → Check for updates command and a direct link to the download page;
• no cloud AI service and no transmission of health data to the developer;
• robust system-language detection, a persistent Settings → Language selector, English fallback, and community catalogues managed through Weblate.

Quick start

1. Download the package for your operating system from the latest release.

2. Start VitalChronicle.

3. Select Google setup and follow the wizard.

4. Create a personal Google Cloud project, enable the Google Health API, and add your account as a test user if the OAuth project is in Testing mode.

5. Create an OAuth client of type Web application with this exact redirect URI:

   http://localhost:8765/
   

6. Download the OAuth JSON once and import it in the wizard.

7. Sign in through the browser and select Download / update.

The complete procedure, screenshots, scope list, and troubleshooting steps are in the detailed user manual. A versioned PDF manual is attached to every release.

Install from source

Python 3.10 or newer is required. On Fedora:

sudo dnf install python3 python3-pip
git clone https://github.com/SebRoLENS/google-health-dashboard-ai.git
cd google-health-dashboard-ai
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
vitalchronicle

On Windows activate the environment with .venv\Scripts\activate; on macOS and other Unix-like systems use source .venv/bin/activate.

Google OAuth: Testing or Production?

Testing mode is convenient for personal use and does not require public verification. Add the intended Google accounts under Audience → Test users. For an external OAuth project in Testing, Google normally issues refresh tokens that expire after seven days, so VitalChronicle may occasionally ask the user to sign in again.

Production status is not mandatory for personal use. Publishing an app that requests sensitive or restricted scopes to a wider audience can require Google verification. Each VitalChronicle user creates and controls their own OAuth client; client secrets and tokens must never be committed to GitHub or shared with the developer.

Local AI setup

Install Ollama, start its service, and pull a compatible model. For example:

ollama pull qwen3.5:9b
ollama list
curl -sS http://127.0.0.1:11434/api/version

VitalChronicle does not present local-model output as a diagnosis. Wearable data may be incomplete or inaccurate, correlations do not establish causality, and important health decisions should be discussed with a qualified professional.

Documentation

• Detailed manual
• Quick start
• Release and maintenance guide
• Changelog
• Security policy
• Contributing guide

Privacy and data ownership

Health data are stored in a private local SQLite database. OAuth credentials use the system keyring when available and otherwise fall back to a user-readable local file with restricted permissions. Local Ollama analysis is sent only to 127.0.0.1. The only remote services contacted are Google for authorised health-data access and the Ollama registry when checking whether model weights have changed.

The application deliberately retains the historical internal GoogleHealthViewer data directory name so that upgrading from 0.2.12 to current VitalChronicle releases preserves existing records, credentials, and settings.

Support development

VitalChronicle is developed as free, open-source software and will remain so. No feature is placed behind a donation. If the project saves you time, you can support its continued development on Buy Me a Coffee.

An equally useful non-financial contribution is to translate the application on Weblate. Translations committed by Weblate are validated by GitHub Actions and included automatically in subsequent application releases.

The same link is available inside the application toolbar and Help menu.

Author and contact

Sebastiano Romi
sebastiano.romi@gmail.com

Bug reports and feature requests belong in the GitHub issue tracker.

License

VitalChronicle is released under the MIT License. The source code is public, and the software is free to use, study, modify, and redistribute under that license.

If you would like to help the project while keeping it open for everyone, Buy Me a Coffee.