Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ These checks need no Garmin account, key, live archive, client registration, or
| `src/garmin_archive/archive.py` | SQLite schema, stored source data and archive writes |
| `src/garmin_archive/fit.py` | Original activity ZIP handling and FIT decoding |
| `src/garmin_archive/queries.py` | Shared metric definitions, daily summaries and trends |
| `src/garmin_archive/comparisons.py` | Covered comparisons of two explicit metric periods |
| `src/garmin_archive/workouts.py` | Activity filtering and covered daily/weekly distance and duration totals |
| `src/garmin_archive/sources.py` | Documented Personal API endpoints and collection scopes |
| `src/garmin_archive/api_data.py` | Native field catalog, bounded response browsing and scalar series |
| `src/garmin_archive/sleep.py` | Bounded sleep fields, source window times and stage completeness |
Expand Down
2 changes: 2 additions & 0 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ The MVP uses only Garmin's official Personal API. [The coverage contract](docs/A

`sources.py` owns collection routes; the packaged response contract owns schema discovery. `api_data.py` provides shared bounded native field access and scalar series. Native access preserves source values, flags and sentinels; interpreted daily metrics in `queries.py` apply documented mappings and validity rules. Every field is accessible without requiring a separate tool or invented daily aggregate. Coordinates are omitted from default MCP responses and require an explicit native-source opt-in.

`comparisons.py` compares existing metric trends using two explicit periods and available-day denominators. `workouts.py` owns shared activity filtering and daily/weekly volume totals from search summaries. Failed activity refreshes mask measurements; stored multisport parent IDs prevent counting parents alongside their children. These are read-only interpretations over the existing schema, with no collector, scheduler or dependency additions. Provider-specific automation remains with the assistant; native schedule configuration is not proof of unattended execution.

[Schema and SQL](docs/USAGE.md#sql-and-source-data) · [Sync behavior](docs/USAGE.md#sync-and-recovery)

## Concurrency and durability
Expand Down
47 changes: 41 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,26 +7,61 @@ Help with sync reliability, data coverage, FIT decoding, queries, assistant setu
Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/):

```sh
uv sync --locked
uv run python -m unittest discover -s tests -v
uv run garmin-archive --help
uv run garmin-archive-mcp --help
git clone https://github.com/0xBreadguy/garmin-data-workbench.git
cd garmin-data-workbench
uv sync --locked --extra charts
uv run --locked --extra charts python -m unittest discover -s tests -v
uv run --locked --extra charts garmin-archive --help
uv run --locked --extra charts garmin-archive-mcp --help
```

Tests use synthetic data and fake responses. No Garmin account or key required; dependency installation may need network access.

Use `uv run` for development. Installed `uv tool` copies don't pick up edits. Change dependencies deliberately: run `uv lock`, then review `pyproject.toml` and `uv.lock` together.
Fork the repository first if you need your own push destination. If you already have a checkout, start with the `uv` commands. The charts extra enables rendering tests; a base-only environment skips those tests. Keep `--extra charts` on subsequent `uv run` commands when checking chart behavior.

Use `uv run` for development. Installed `uv tool` copies don't pick up edits. Change dependencies deliberately: run `uv lock`, then review `pyproject.toml` and `uv.lock` together. Don't run `install`, `sync`, `setup` or the live connection script as a development smoke test.

## Where a change belongs

The installable Python package lives in `src/garmin_archive/`. CLI and MCP are adapters over the same local query code; neither should define a separate interpretation of a metric.

| Change | Start here | Verification |
| --- | --- | --- |
| Collection, retries or resumability | `sources.py`, `sync.py`, `cli.py` sync orchestration | `test_archive.py`, `test_catchup.py`, `test_contract_corpus.py` |
| Archive/schema or FIT decoding | `archive.py`, `fit.py` | `test_archive.py`, `test_fit_corpus.py`; older synthetic archive compatibility |
| A named metric or its meaning | `queries.py`, `sleep.py`, `body_battery.py` | Domain tests and matching CLI/MCP results |
| Period comparisons or workout filtering/totals | `comparisons.py`, `workouts.py` | `test_comparisons_workouts.py`, CLI/MCP parity and installed-wheel smoke |
| Native API fields or pagination | `api_data.py`, `sources.py`, `personal_api_contract.json` | `test_api_data.py`, `test_contract_corpus.py`; [contract maintenance](docs/API_COVERAGE.md#verification-and-contract-maintenance) |
| Charts and delivery | `charts.py`, `chart_delivery.py`, `brand.json`, `assets/` | `test_charts.py`, `test_chart_delivery.py`, `test_cli_chart_metadata.py`; inspect a synthetic render |
| Commands or tool surfaces | `cli.py`, `mcp_server.py` | `test_cli_queries.py`, `test_workbench_mcp.py`; installed-wheel smoke for entry-point changes |
| Setup, host behavior or scheduling | `install.py`, `onboarding.py`, `platforms.py`, `schedule.py` | Corresponding test files; OS-specific behavior stays at these boundaries |
| User or assistant guidance | `README.md`, `docs/`, `agent_guide.md`, `skills/` | Check commands and links; keep installed guidance aligned with repository docs |

Python paths in this table are relative to `src/garmin_archive/`; tests live in `tests/`. [`AGENTS.md`](AGENTS.md#repository-map) has the full module map and [`docs/TESTING.md`](docs/TESTING.md#focused-checks) lists focused test commands. You don't need an agent, private tooling or a live Garmin account to contribute.

Start with a small bug, a clearer error, a synthetic edge case or a documentation correction. Use issues to discuss new collectors, storage/durability changes, metric interpretations or new integration claims before building them. The current collection scope is Garmin's official Personal API.

## Make a change

1. Check Git status, use an isolated branch and preserve existing work.
2. Read [AGENTS.md](AGENTS.md) and [ARCHITECTURE.md](ARCHITECTURE.md). Keep collection, storage, shared queries and adapters separate.
3. Add focused offline tests for changed behavior. Preserve source data, units, dates and the distinction between missing, empty, failed and stale values.
3. Add focused offline tests for changed behavior. Preserve source data, units, dates and the distinction between missing, empty, failed and stale values. Use invented fixtures; never anonymize a personal archive into a test fixture.
4. Run the [relevant checks](docs/TESTING.md), inspect the diff and run `git diff --check`. Run `uv build` for packaging changes.
5. Open a PR explaining the user-visible change, verification and remaining gaps.

Use the existing Python, unittest and uv conventions. There is no separate lint, formatter or type-check gate. Before pushing or merging to the default branch, the full suite and required release checks must pass for that revision; exact-revision CI counts.

For a focused check, replace the filename with the affected test:

```sh
uv run --locked --extra charts python -m unittest discover -s tests -p 'test_queries.py' -v
git diff --check
```

Keep a PR focused on one problem and describe the resulting behavior, checks and remaining limits in the [PR template](.github/pull_request_template.md). Include user-facing docs when behavior changes. API/schema changes need preservation and compatibility evidence; rendered changes need synthetic visual inspection. Don't bundle unrelated reformatting or generated archives. Contributions use the repository's [MIT license](LICENSE).

Maintainers: follow [the release checklist](docs/RELEASING.md) for dependency review, required CI and a tagged release. Passing the offline suite doesn't establish live host or assistant support.

## Report a problem

Include the source revision, OS/Python version, command or client, expected behavior and sanitized result. For a new host or assistant, use the [setup report](.github/ISSUE_TEMPLATE/setup-report.md). Distinguish installation, discovery, sync, a real query and actual scheduled execution.
Expand Down
36 changes: 36 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,25 @@
<img src="assets/logo.svg" alt="Two conversation bubbles joined by a data line" width="180">

[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-4B6F92?style=flat-square)](https://www.python.org/)
[![Main package smoke](https://github.com/0xBreadguy/garmin-data-workbench/actions/workflows/tests.yml/badge.svg?branch=main&event=push)](https://github.com/0xBreadguy/garmin-data-workbench/actions/workflows/tests.yml)
[![SQLite archive](https://img.shields.io/badge/archive-SQLite-5C7D70?style=flat-square)](https://www.sqlite.org/)
[![MIT license](https://img.shields.io/badge/license-MIT-777777?style=flat-square)](LICENSE)

**Your Garmin data, ready for your agent or your own analysis.**

Sync health data and activities into a SQLite archive on your computer or a persistent remote workstation. Keep the source JSON and original activity files. Ask your agent questions through MCP or the CLI, or work directly with SQL, scripts, notebooks and CSV.

- Review sleep, Body Battery, heart rate, steps and activities with dates, units and coverage.
- Compare two metric periods and review workout distance/duration totals by date and sport.
- Generate charts from the same stored data your agent queries.
- Explore native fields from all 26 documented Personal API endpoints and retain original activity files for your own analysis.

This is an early **0.1.0** workbench. Start with the synthetic demo or a short sync, and check the [tested hosts and assistant paths](docs/COMPATIBILITY.md) before relying on an integration.

![Muse answers a sleep question for April 24–30, 2026, with a concise summary and an attached sleep overview. The conversation is labeled as a synthetic demo.](assets/muse-sleep-demo.png)

A captured Muse conversation using generated demo data. The assistant reported using the CLI; this capture demonstrates visible answers and chart delivery. Appearance and connection options depend on your assistant. [Image provenance](assets/README.md).

## Get started

**Working with an agent?** Give it this repository and ask:
Expand All @@ -35,8 +47,16 @@ uv tool install --from . garmin-data-workbench

Follow the [setup guide](docs/SETUP.md) to create your Garmin Personal API key and run a first sync. Guided setup supports Codex and Claude Code; other agents can use local MCP or shell commands. Built-in scheduling supports macOS; remote workstations can use an OS scheduler or provider routine.

For charts, replace the install command with `uv tool install --from '.[charts]' garmin-data-workbench`.

Keep your key out of chat. On a remote workstation, processes sharing your OS user can read credentials and health data. Query results may reach your agent's AI provider. Choose the host before syncing.

### Try it without a Garmin key

Follow the [isolated demo setup](docs/SETUP.md#mock-only-setup-stop-before-credentials) to generate synthetic data in a new archive, with its own checkout and environment. It makes no Garmin requests and preserves existing installations. An agent can start with:

> Read AGENTS.md and follow the mock-only route in docs/SETUP.md. Use a new checkout, environment and synthetic archive. Leave my existing installation, credentials, data and schedules unchanged. Show me the sleep overview for April 24–30, 2026.

## Use your archive

Ask your agent: “How did my sleep and resting heart rate change over the last week?” Or query it yourself:
Expand All @@ -50,6 +70,20 @@ garmin-archive trend sleep_duration --from 2026-01-01 --to 2026-01-07

Queries use stored data. Available history and fields depend on Garmin, your devices and what was recorded.

![Synthetic sleep overview for April 24–30, 2026, showing sleep duration, stages, Garmin sleep need and a separate sleep score panel.](assets/sleep-example.png)

Example output from the [generated demo](docs/VISUALIZATION.md#try-generated-demo-data), not personal health data. Collection timestamps are simulated; wearable scores and stages are estimates.

## What works where

| Path | Current boundary |
| --- | --- |
| CLI and local archive | Offline CI covers macOS, Windows and Linux with Python 3.12. Live Windows credential/privacy validation is still incomplete. |
| Agents | Shell access or local stdio MCP. Codex and Claude Code have guided registration; each assistant connection needs its own query test. |
| Automatic sync | Built-in macOS scheduling. Other hosts need their own scheduler or provider routine. |

See [assistant connections](docs/ASSISTANTS.md) for remote access and the checks behind each compatibility claim. Garmin's Personal API is for individuals accessing their own data; review [Garmin's FAQ and terms](https://developer.garmin.com/gc-developer-program/personal/personal-faq/) before live setup.

## Go deeper

- [Commands, SQL, exports and scheduling](docs/USAGE.md)
Expand All @@ -58,4 +92,6 @@ Queries use stored data. Available history and fields depend on Garmin, your dev
- [Contribute](CONTRIBUTING.md) · [Agent instructions](AGENTS.md) · [Testing](docs/TESTING.md)
- [Architecture](ARCHITECTURE.md) · [Security](SECURITY.md)

Found a problem? Open a [bug report](https://github.com/0xBreadguy/garmin-data-workbench/issues/new?template=bug-report.md) or [setup report](https://github.com/0xBreadguy/garmin-data-workbench/issues/new?template=setup-report.md) with a synthetic reproduction. Keep credentials, personal health data and routes out of public issues. Report vulnerabilities through [the security policy](SECURITY.md).

Independent open-source project. Not affiliated with, endorsed by, or supported by Garmin.
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Keep keys, tokens, health records, original activity files and GPS routes out of

## Report a vulnerability

Use private vulnerability reporting in the repository's GitHub Security tab, if available. Otherwise, open an issue requesting a private channel, without exploit details or sensitive data.
Use [GitHub private vulnerability reporting](https://github.com/0xBreadguy/garmin-data-workbench/security/advisories/new). If that route is unavailable, open an issue requesting a private channel, without exploit details or sensitive data.

Privately provide the source revision, affected component, impact and a synthetic reproduction. Don't attach an archive or credentials. Fixes target current code unless a maintainer says otherwise; no response time or older-release support is promised.

Expand Down
15 changes: 15 additions & 0 deletions assets/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Documentation and brand assets

`logo.svg`, `icon.svg` and `icon.png` are the Workbench brand assets. The installed package includes these fixed resources for CLI/MCP charts; documentation screenshots are not runtime resources.

## Muse sleep demonstration

`muse-sleep-demo.png` is a reviewed privacy crop of an actual Muse app screenshot captured November 4, 2026. Its question, answer and chart thumbnail are unchanged. No dialogue, number or UI element was replaced. It uses generated corpus v2, seed 42, with April 24–30, 2026 dates and simulated collection timestamps; no personal health records are shown.

The app interaction and visible attachment were directly observed. The agent reported CLI use on an Ubuntu workstation and source revision `47dcd68`; remote execution details were not independently audited. This screenshot does not establish live Garmin collection, MCP support, persistence or recurring execution. Muse is a separate assistant application, not a UI shipped by this repository.

SHA-256: `53d9f77e788383d47d68e6cbab490c79a6537f252cd063954af9bf61c523928c`.

## Sleep chart preview

`sleep-example.png` is a direct Workbench export from the same default generated corpus and dates, using the `wide` layout. It is not an assistant screenshot. See [reproduction instructions](../docs/VISUALIZATION.md#keep-images-concise). Charts remain illustrative wearable estimates; the generated scores and stages do not establish physiological relationships.
Binary file added assets/muse-sleep-demo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/sleep-example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 3 additions & 1 deletion docs/ASSISTANTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,9 @@ Replace the executable path. For a custom archive, use `args: ["--data-dir", "/a

### Tool contract

Sixteen tools read data/status/guidance; `configure_sync` changes the local macOS schedule when requested. Data tools need no Garmin credentials and make no live requests.
Eighteen tools read data/status/guidance; `configure_sync` changes the local macOS schedule when requested. Data tools need no Garmin credentials and make no live requests.

`compare_periods` calculates changes between two explicit metric periods. `get_workout_summary` returns covered activity distance/duration totals and weekly buckets; `list_activities` also supports date/type filters. See [comparison and workout semantics](USAGE.md#compare-periods-and-summarize-workouts).

They provide daily summaries, up to 90 days of [trend metrics](USAGE.md#summaries-units-and-dates), detailed [sleep summaries](SLEEP.md), [Body Battery summaries](BODY_BATTERY.md), coverage, activities, stored daily responses and paginated FIT records. `agent_guide` returns installed guidance; `setup_receipt` separates setup evidence from outstanding verification. Samples omit coordinates and raw fields. `api_catalog` discovers all documented Personal API sources and native field definitions. `source_data` pages their complete stored responses; `source_series` reads native scalar values across dates. Default output omits coordinates; native coordinate access requires an explicit opt-in. See [Personal API coverage](API_COVERAGE.md). `daily_health` responses over 64 KB are rejected; use `source_data` to page them. Failed refreshes mask retained response data.

Expand Down
Loading
Loading