health-agent 0.1.1 → 0.1.3

package/README.md

@@ -12,6 +12,12 @@ npm install -g health-agent     # installs the `health-agent` command
 pnpm install -g health-agent
 ```
 
+As a Claude Code / agent skill (teaches the agent how to drive the CLI):
+
+```bash
+npx skills add code-vagabond/health-agent
+```
+
 As a Claude Code plugin (bundles the skill so Claude knows how to drive the CLI):
 
 ```bash
@@ -64,6 +70,20 @@ health-agent raw 'users/me/dataTypes/steps/dataPoints'   # escape hatch
 
 JSON goes to stdout, diagnostics to stderr — pipe to `jq` freely.
 
+## Use cases — let the agent cross-reference your life
+
+The CLI just emits JSON. The interesting part is handing that to an agent (Claude Code) that *also* has access to your other data, so it can correlate signals you'd never line up by hand. A few that work today:
+
+- **Sedentary reminder** — flag when heart rate has stayed at a flat resting level for hours with no active spike, and ping you to move.
+- **"How did my week actually go?"** — the agent pulls `steps`, `sleep`, and `exercise`, then cross-references your calendar (Google Calendar / Outlook MCP) to explain the dips: *"Your sleep dropped to 5h on the three nights before the investor call, and step count cratered the day after."*
+- **Sleep vs. focus** — combine `sleep` with your ScreenTimerAI activity log (or any time-tracking export). Ask *"do I ship more on days after 7h+ of sleep?"* and let the agent regress one against the other.
+- **Workout log → training insight** — `get exercise` carries the full Hevy set/rep/weight log in `.exercise.notes`. The agent can chart progressive overload, flag stalled lifts, or suggest next-session weights — no separate fitness app needed.
+- **Stress / health journal correlation** — pair `health_metrics` (resting HR, body metrics) with your personal journal entries. *"Resting HR was elevated every day you logged feeling 'overwhelmed' — and those clustered around two specific deadlines."*
+- **Standup / weekly review** — at the end of the week, have the agent fold health into your work recap: a one-paragraph "you" report that treats sleep and movement as first-class inputs alongside commits and meetings.
+- **Recovery-aware planning** — before the agent plans tomorrow, it checks last night's `sleep` and today's `steps`. Slept badly? It front-loads lighter tasks and pushes the deep-work block.
+
+Because everything is JSON on stdout, you can also wire it into a cron/`/schedule` job that drops a daily digest into a file, a Slack message, or a note — without the agent ever touching your Google login.
+
 ## Data model notes
 
 - **Reconciled stream** (`--reconcile` / `-w`): deduped data matching what the Fitbit app shows. The plain list returns raw per-source data points.

package/SKILL.md

@@ -86,6 +86,8 @@ At the browser screen, tell the user to:
 health-agent steps
 health-agent sleep
 health-agent exercise
+health-agent resting-hr     # daily RESTING heart rate (one value/day, calc'd from sleep). Aliases: resting-heart-rate, rhr
+health-agent bpm            # raw live heart-rate samples (latest spot reading, NOT resting). Aliases: heart-rate, hr
 
 # Any data type (kebab-case id): steps, sleep, exercise, body-fat, ...
 health-agent get steps --wearables --limit 50

package/dist/index.js

@@ -278,6 +278,46 @@ async function rawGet(pathAndQuery) {
   return authedGet(pathAndQuery.replace(/^\/+/, ""));
 }
 
+// src/localize.ts
+function parseOffsetSeconds(raw) {
+  if (typeof raw !== "string") return null;
+  const m = /^(-?\d+)s$/.exec(raw.trim());
+  return m ? parseInt(m[1], 10) : null;
+}
+function toLocalIso(utc, offsetSeconds) {
+  const ms = Date.parse(utc);
+  if (Number.isNaN(ms)) return null;
+  const shifted = new Date(ms + offsetSeconds * 1e3).toISOString().replace(/(\.\d+)?Z$/, "");
+  const sign = offsetSeconds < 0 ? "-" : "+";
+  const abs = Math.abs(offsetSeconds);
+  const hh = String(Math.floor(abs / 3600)).padStart(2, "0");
+  const mm = String(Math.floor(abs % 3600 / 60)).padStart(2, "0");
+  return `${shifted}${sign}${hh}:${mm}`;
+}
+function localizeTimes(node) {
+  if (Array.isArray(node)) {
+    for (const item of node) localizeTimes(item);
+    return node;
+  }
+  if (node && typeof node === "object") {
+    const obj = node;
+    for (const key of Object.keys(obj)) {
+      const m = /^(.*)Time$/.exec(key);
+      if (m && typeof obj[key] === "string") {
+        const base = m[1];
+        const offset = parseOffsetSeconds(obj[`${base}UtcOffset`]);
+        if (offset !== null) {
+          const local = toLocalIso(obj[key], offset);
+          if (local) obj[`${base}TimeLocal`] = local;
+        }
+      }
+      localizeTimes(obj[key]);
+    }
+    return node;
+  }
+  return node;
+}
+
 // src/commands/data.ts
 function toOpts(args) {
   const reconcile = args.reconcile || args.wearables || !!args.source;
@@ -294,7 +334,8 @@ function emit(data) {
 }
 async function getData(dataType, args) {
   try {
-    emit(await getDataPoints(dataType, toOpts(args)));
+    const data = await getDataPoints(dataType, toOpts(args));
+    emit(args.local ? localizeTimes(data) : data);
   } catch (e) {
     console.error(`\u274C ${e.message}`);
     process.exit(1);
@@ -329,7 +370,11 @@ var dataOpts = (y) => y.option("reconcile", {
   alias: "f",
   describe: `Google Health filter, e.g. 'sleep.interval.civil_end_time >= "2026-03-03"'`,
   type: "string"
-}).option("limit", { alias: "n", describe: "Max data points (pageSize)", type: "number" }).option("page-token", { describe: "Pagination token from a previous response", type: "string" });
+}).option("limit", { alias: "n", describe: "Max data points (pageSize)", type: "number" }).option("page-token", { describe: "Pagination token from a previous response", type: "string" }).option("local", {
+  describe: "Add <field>Local wall-clock times (UTC + the record's UtcOffset) next to each UTC timestamp",
+  type: "boolean",
+  default: false
+});
 yargs(hideBin(process.argv)).scriptName("health-agent").usage("$0 <command> [options]").command(
   "auth:setup",
   "Store your Google Cloud OAuth client (Desktop app type)",
@@ -350,7 +395,8 @@ yargs(hideBin(process.argv)).scriptName("health-agent").usage("$0 <command> [opt
     source: a.source,
     filter: a.filter,
     limit: a.limit,
-    pageToken: a.pageToken
+    pageToken: a.pageToken,
+    local: a.local
   })
 ).command(
   "steps",
@@ -367,6 +413,19 @@ yargs(hideBin(process.argv)).scriptName("health-agent").usage("$0 <command> [opt
   "Fetch exercise/activity sessions (reconciled, Fitbit/Pixel)",
   dataOpts,
   (a) => getData("exercise", { ...a, wearables: a.wearables || !a.reconcile && !a.source })
+).command(
+  ["resting-hr", "resting-heart-rate", "rhr"],
+  "Fetch daily resting heart rate (one value per day, calculated from sleep)",
+  dataOpts,
+  (a) => getData("daily-resting-heart-rate", {
+    ...a,
+    wearables: a.wearables || !a.reconcile && !a.source
+  })
+).command(
+  ["heart-rate", "bpm", "hr"],
+  "Fetch raw heart-rate samples (latest live BPM readings, not resting HR)",
+  dataOpts,
+  (a) => getData("heart-rate", { ...a, wearables: a.wearables || !a.reconcile && !a.source })
 ).command("profile", "Fetch your user profile", {}, () => getProfile()).command(
   "raw <path>",
   'GET any path under the v4 base, e.g. "users/me/dataTypes/steps/dataPoints"',

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "health-agent",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI + Claude skill to authenticate with the Google Health API and pull your Fitbit / Pixel health data",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "health-agent": "./dist/index.js"
+    "health-agent": "dist/index.js"
   },
   "scripts": {
     "dev": "tsup --watch",