Google has released ghealth, a new open-source command-line tool that bridges the gap between health data and artificial intelligence. The tool wraps Google's Health API v4, the official successor to the Fitbit Web API, and is specifically designed to make health data accessible to AI agents and terminal users. Built as a single Go binary under the Apache 2.0 license, ghealth exposes 40 verified data types as structured JSON, allowing developers and AI systems to easily pipe sleep, heart rate, step counts, and other health metrics into agent contexts.

What Health Data Can AI Agents Access Through ghealth?

The tool covers most signals from Fitbit devices and Pixel Watch smartwatches. The 40 supported data types include basic metrics like steps, heart rate, sleep, weight, oxygen saturation, and heart rate variability. More specialized clinical data, such as electrocardiogram readings, are also available but require specific security clearance through the ecg.readonly scope.

Each data type supports different operations depending on whether it's read-only or writable. Common operations include list, rollup, and daily-rollup functions that aggregate data over time. For writable types like exercise, sleep, weight, body fat, and height, users can also create, update, and delete entries. A reconcile operation merges overlapping data points from multiple sources, mirroring the Reconciled Stream feature in the underlying API.

How to Use ghealth for Health Data Analysis?

• Setup Process: Installation requires running a single command, ghealth setup, which launches a wizard that guides users through Google Cloud Platform project configuration and OAuth authentication. Users create a Desktop-type OAuth client in the Google Cloud Console and maintain their own credentials locally.
• Data Retrieval: Commands follow a consistent pattern, such as ghealth data heart-rate list to fetch recent readings or ghealth data steps daily-rollup to get aggregated step totals over a specific date range. Output defaults to simplified JSON but can be converted to CSV or table formats using the --format flag.
• Agent Integration: The tool is explicitly designed for AI agents, returning deterministic exit codes and stable JSON shapes. Developers can pipe sleep patterns into Claude Code sessions to analyze deep-sleep trends, load workout data into pandas for analysis, or build custom dashboards from resting heart rate data collected over 30 days.
• Security Features: All data is stored locally under ~/.config/ghealth/ with file mode 0600 permissions. The tool uses PKCE with an S256 challenge for headless authentication flows and validates random state parameters on completion. Tokens refresh automatically without requiring a shared key.

The tool ships with two Agent Skills documented in SKILL.md files. One covers authentication, setup, and global flags, while the other documents all 40 data types, supported operations, common patterns, and potential gotchas. Agents can install these skills using npx skills add.

How Does ghealth Compare to Other Health Data Tools?

ghealth stands apart from the raw Google Health API v4 and other community-built alternatives in several ways. The raw API requires developers to handle HTTP or gRPC calls directly and manage complex authentication themselves. Two other community-built command-line tools exist, but both explicitly identify themselves as unofficial and lack the same level of verification against the live API.

For developers who need raw control and access to the full v4 API surface, the direct REST API remains the ground truth. However, for terminal and AI agent use cases, ghealth significantly reduces authentication boilerplate and standardizes output formatting. The tool's agent-first design means every command returns simplified JSON with a stable shape, making it far easier for AI systems to parse and act on health data without custom parsing logic.

The repository lives under the Google-Health-API GitHub organization, which also maintains long-standing Fitbit open-source repositories. While ghealth is not an official Google product, its placement within Google's own GitHub organization signals community support and ongoing maintenance.

What Does This Mean for Health Data Privacy?

All Google Health API scopes are classified as Restricted, meaning Google requires a privacy and security review before granting production access to external developers. For personal use, users authorize their own projects against their own accounts, and the API returns data only from Fitbit, Pixel Watch, and connected third-party sources that the user has explicitly linked.

The tool's design emphasizes local security. Users bring their own OAuth credentials, and ghealth holds no shared key. This means each installation maintains complete control over its authentication tokens and health data, with no central server storing credentials or data on behalf of the user.