What makes Health Metrics notable?

3.1K downloads. Trust evidence available

How should Health Metrics be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

Health Metrics

Ingest Apple Health Auto Export JSON (HealthMetrics + Workouts) into a local DuckDB database and render offline HTML dashboards plus a Markdown daily summary...

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

3.1k

Updated

Oct 9, 2026

Version

0.1.1

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 3.1K downloads reported by the source. Last updated 10/9/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 9, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 9, 2026
Adoption signal: 3.1K downloadsadoption · observed Oct 9, 2026
Latest release: 0.1.1release · observed Jul 22, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s17fh7c035hba497j017fat8rd88496r:health-metrics

Install using `clawhub skill install s17fh7c035hba497j017fat8rd88496r:health-metrics` in an isolated environment before connecting it to live workloads.
No published capability contract is available yet, so validate auth and request/response behavior manually.
Review the upstream CLAWHUB listing at https://clawhub.ai/bartsoj/health-metrics before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-bartsoj-health-metrics/snapshot"

Documentation

CLAWHUB

42,502 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: health-metrics
description: >-
  Ingest Apple Health Auto Export JSON (HealthMetrics + Workouts) into a local DuckDB
  database and render offline HTML dashboards plus a Markdown daily summary (activity
  rings, training load, sleep, vitals, per-workout maps). Use when the user wants to
  process Apple Health exports, refresh their health dashboards, or get a training-load /
  rings / sleep / vitals report from their exported data.
version: 1.1.0
metadata:
  openclaw:
    emoji: "🏃"
    requires:
      bins: ["python3", "duckdb"]
    env: ["HEALTH_METRICS_DIR", "HEALTH_WORKOUTS_DIR", "HEALTH_DB_PATH"]
    os: ["macos", "linux"]
---

# Health Metrics

A self-contained pipeline that ingests **Apple Health Auto Export** JSON feeds into a local
DuckDB database and renders static, offline-first HTML dashboards plus an AI-oriented Markdown
digest. No web server, no scheduler, no pip packages — just Python stdlib and the `duckdb` CLI.
You run it on demand whenever new export files land.

## Prerequisites

- `python3` and the `duckdb` CLI binary on `PATH` (no Python `duckdb` package needed).
- Apple Health Auto Export daily JSON files available on disk (see **Configuration**).
- Internet is needed only to *view* workout route maps (Leaflet + satellite tiles from a CDN).
  Everything else renders fully offline.

## Normal workflow

Regenerate everything after new exports arrive:

```bash
python3 {baseDir}/scripts/ingest.py && python3 {baseDir}/scripts/report.py -o <OUT_DIR>
```

- `ingest.py` reads the source JSON and upserts into the DuckDB file (idempotent — safe to
  re-run; unchanged files are skipped).
- `report.py -o <OUT_DIR>` writes all dashboards into a directory **you choose**. Pick a working
  or output directory the user controls; do not write inside the skill folder.

## One-command runner (`scripts/run.sh`) — recommended

`scripts/run.sh` wraps the pipeline and handles two things the raw scripts do not:

1. **Materializes iCloud placeholder files** before ingest (see the gotcha below).
2. **Always ingests before rendering**, so reports never show stale data.

```bash
bash {baseDir}/scripts/run.sh daily-md [YYYY-MM-DD] [OUT_DIR]   # ingest -> flat <OUT_DIR>/YYYY-MM-DD.md (default date = today)
bash {baseDir}/scripts/run.sh html [OUT_DIR]                    # ingest -> full HTML dashboard set in OUT_DIR
bash {baseDir}/scripts/run.sh ingest                           # materialize + ingest only
```

Output dirs: `daily-md` defaults to `$HEALTH_MD_DIR` (else `reports/summary`); `html` defaults
to `$HEALTH_HTML_DIR` (else a timestamped `reports/html-*`). `html` prints `HTML_OUT_DIR=<dir>`
on the last lines. Exits non-zero on failure so schedulers surface it.

**Use `daily-md` from a scheduler** to keep a per-day Markdown log current (e.g. a nightly cron
that writes into a knowledge/notes folder), and **`html` on demand** for shareable dashboards.

### ⚠️ iCloud "dataless placeholder" gotcha (macOS)

Apple Health Auto Export writes into

README.md

# health-metrics

An **Agent Skill** for **Apple Health Auto Export** reporting and logging. It lets an agent
(OpenClaw, Claude Code, or any tool that reads the portable `SKILL.md` format) ingest Apple
Health Auto Export JSON feeds into a local DuckDB database and render offline, self-contained
HTML dashboards plus a Markdown daily digest — activity rings, training load, sleep, vitals,
and per-workout maps.

No web server, no scheduler, no Python packages beyond the stdlib + the `duckdb` CLI. Runs on
demand whenever new export files land.

## Quick start

```bash
python3 scripts/ingest.py && python3 scripts/report.py -o <OUT_DIR>
```

- `ingest.py` parses the Apple Health Auto Export daily JSON and upserts into DuckDB (idempotent).
- `report.py -o <OUT_DIR>` renders all dashboards into a directory you choose.

Or use the one-command runner, which ingests first and (on macOS/iCloud) force-downloads any
evicted placeholder files before reading them:

```bash
bash scripts/run.sh daily-md [YYYY-MM-DD] [OUT_DIR]   # Markdown daily summary (default: today)
bash scripts/run.sh html [OUT_DIR]                    # full HTML dashboard set
bash scripts/run.sh ingest                            # materialize + ingest only
```

> **macOS / iCloud note:** if the source folders live in iCloud Drive with "Optimize Mac
> Storage" on, reads can fail with `Resource deadlock avoided` until files are downloaded.
> `run.sh` handles this automatically; the permanent fix is Finder → right-click each source
> folder → **Keep Downloaded**. See [`SKILL.md`](SKILL.md) for details.

Source folders and the database location are configurable via environment variables
(`HEALTH_METRICS_DIR`, `HEALTH_WORKOUTS_DIR`, `HEALTH_DB_PATH`), with sensible defaults.

## Learn more

- **[`SKILL.md`](SKILL.md)** — the skill entry point: prerequisites, workflow, configuration, and
  every runnable stage.
- **[`references/architecture.md`](references/architecture.md)** — internals (data flow, ingestion
  pattern, report conventions, `scripts/lib/` helpers).
- **[`references/schema.md`](references/schema.md)** — the DuckDB table reference.

## Data & privacy

The DuckDB database is **personal, sensitive health data**. It is created on first ingest, lives
**outside** this repository (default `~/.local/state/health-metrics/health.duckdb`), and is never
committed, published, or bundled.

## License

[MIT No Attribution (MIT-0)](LICENSE).

_meta.json

{
  "ownerId": "kn75shmdha8pdb93g5rpghnw6s80knmx",
  "slug": "health-metrics",
  "version": "0.1.1",
  "publishedAt": 1784714747586
}

references/architecture.md

# Architecture

Internals of the `health-metrics` skill — read this before modifying the scripts or adding a new
report/metric. Operational usage lives in `../SKILL.md`; the table reference in `./schema.md`.

## Data flow

```
Apple Health Auto Export folders (source JSON, outside this skill)
-> scripts/ingest_*.py (parse + normalize, idempotent upsert into the DuckDB file)
-> scripts/report_*.py (query DuckDB, render self-contained HTML/Markdown into an out-dir)
```

Source JSON lives outside the skill, in the Apple Health Auto Export folders. The folders are
configurable via `HEALTH_METRICS_DIR` / `HEALTH_WORKOUTS_DIR` (see `../SKILL.md`); the defaults
point at the standard iCloud locations:

- `…/iCloud~com~ifunography~HealthExport/Documents/iCloud Drive HealthMetrics/HealthMetrics-YYYY-MM-DD.json`
- `…/iCloud Drive Workouts/Workouts-YYYY-MM-DD.json`

Each ingester only reads **daily** files (`HealthMetrics-YYYY-MM-DD.json` /
`Workouts-YYYY-MM-DD.json`). Weekly/monthly/yearly rollup files in those same folders are ignored.

The DuckDB file location comes from `HEALTH_DB_PATH` (default
`~/.local/state/health-metrics/health.duckdb`), resolved centrally by `scripts/lib/query.py`'s
`db_path()`. It is per-person sensitive state — created on first ingest, never versioned or
bundled.

## Ingestion pattern (`scripts/ingest_health_metrics.py`, `scripts/ingest_workouts.py`)

Both follow the same idempotent shape, invoking the `duckdb` CLI via `subprocess` (never the
`duckdb` Python package):

1. `CREATE TABLE IF NOT EXISTS` schema block, run every time.
2. Glob candidate files matching the strict daily-file regex.
3. Skip a file if its `mtime` matches what's recorded in `ingested_files` / `ingested_workout_files`.
4. Otherwise DELETE-then-INSERT the affected rows in one transaction, then upsert the tracking row.
- `ingest_health_metrics.py` dedupes by `date` (one file = one day = full delete/replace of that
day's rows across all three tables).
- `ingest_workouts.py` dedupes by workout `id`, not by file/day — a workout can appear in
multiple period files with the same `id`, and re-ingesting replaces that workout's rows
wherever it lands.
5. `scripts/lib/metrics.py` is a whitelist: only metrics listed there are kept from HealthMetrics
exports. Anything else (nutrition, weight, mindful minutes, swimming, …) is silently dropped at
ingest time — check that file before assuming a metric name is queryable.
6. `ingest_workouts.py` additionally defends against Apple omitting fields per-workout-type (e.g.
`flightsClimbed` absent for a swim) rather than nulling them — `available_fields()` probes the
file's inferred schema via `DESCRIBE` before building the INSERT, since an all-null/all-absent
JSON field can't be `.qty`-accessed or UNNESTed. Read `WORKOUT_FIELD_EXPRS` in that file before
adding a new workout column.

## Report scripts

All build a full HTML/Markdown string in Python and `write_text()` it into the out-d

references/schema.md

# DuckDB schema

The full analysis surface. Query these tables directly via the `duckdb` CLI or
`scripts/lib/query.py`'s `query(sql)` — there is no ORM, just SQL strings. If a metric you expect
isn't present, check `scripts/lib/metrics.py` first (it whitelists what ingest keeps).

## Analysis tables

- **`samples_qty(date, ts, metric, unit, qty, source)`** — simple quantity samples (steps, active
  energy, …).
- **`samples_hr(date, ts, metric, unit, min, avg, max, source)`** — min/avg/max-per-interval
  metrics (heart_rate).
- **`sleep_sessions(date, ts, in_bed_start, in_bed_end, sleep_start, sleep_end, core, deep, rem,
  awake, asleep, in_bed, total_sleep, source)`**.
- **`workouts(id PK, date, name, start, end, duration_s, is_indoor, location, temperature_c,
  humidity_pct, intensity, distance_km, avg_hr, min_hr, max_hr, avg_speed, max_speed,
  elevation_up_m, active_energy_kj, total_energy_kj, step_cadence, flights_climbed)`** — one row per
  workout.
- **`workout_route(workout_id, seq, ts, lat, lon, altitude, speed, course)`** — GPS points, only for
  outdoor workouts.
- **`workout_hr(workout_id, ts, min, avg, max)`** — per-minute HR during a workout.
- **`workout_hr_recovery(workout_id, seq, ts, min, avg, max)`** — post-workout HR recovery curve.

## Bookkeeping tables (not analysis data)

- **`ingested_files(filename PK, mtime, ingested_at)`** — mtime-based dedup tracking for
  HealthMetrics files.
- **`ingested_workout_files(filename PK, mtime, ingested_at)`** — same, for Workouts files.

Github ReposUpdated 3h agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.