health-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linh Phung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# health-agent
+
+**Read your own Fitbit / Pixel health data from the command line — and let an AI agent drive it.**
+
+A small CLI + Claude Code skill over the [Google Health API](https://developers.google.com/health) (the successor to the Fitbit Web API, which sunsets September 2026). Authenticates with Google OAuth 2.0 and pulls steps, sleep, exercise, body metrics, and profile data as JSON.
+
+## Install
+
+```bash
+npm install -g health-agent     # installs the `health-agent` command
+# or
+pnpm install -g health-agent
+```
+
+As a Claude Code plugin (bundles the skill so Claude knows how to drive the CLI):
+
+```bash
+/plugin marketplace add codevagabond/health-agent
+/plugin install health-agent@health-agent
+```
+
+Local dev:
+
+```bash
+cd ~/code/health-agent && npm install && npm run build && npm link
+```
+
+## One-time setup
+
+The login is human-in-the-loop by design — no agent can (or should) hold your Google login. ~10 minutes, once. **Tip:** ask Claude Code "set up health-agent" and it'll walk you through this step by step (see `SKILL.md`).
+
+1. **Create a project** → https://console.cloud.google.com/projectcreate — name it, and keep it selected in the top bar for the rest.
+2. **Enable the API** → https://console.cloud.google.com/apis/library/health.googleapis.com → **Enable**.
+3. **Consent screen** → https://console.cloud.google.com/auth/audience
+   - If it says *"Google Auth Platform not configured yet"*, click **Get started** and finish the short wizard (app name → support email → Audience: **External** → contact email → Create).
+   - Keep **Publishing status = Testing** (skips the heavyweight restricted-scope verification). Trade-off: refresh tokens expire after 7 days — just `auth:login` again.
+   - **Test users → + Add users** → add the **exact Google account your Fitbit/Pixel syncs to** (and that you'll log in with). Save.
+4. **OAuth client** → https://console.cloud.google.com/auth/clients → **+ Create client** → Application type: **Desktop app** → Create. Copy the **Client ID** + **Secret**.
+   - ⚠️ Must be **Desktop app**, not "Web application" — the CLI uses a `127.0.0.1` loopback redirect, and a Web client gives `redirect_uri_mismatch`.
+5. **Configure + log in**:
+
+   ```bash
+   health-agent auth:setup --client-id <ID> --client-secret <SECRET>
+   health-agent auth:login     # opens browser → Advanced → Go to … (unsafe) → Allow
+   health-agent auth:status
+   ```
+
+Credentials live in `~/.health-agent/` (mode 600). Tokens refresh automatically.
+
+**Gotcha:** *"Access blocked: … has not completed the Google verification process"* means the account you signed in with isn't on the **Test users** list (step 3) — add the exact account, save, retry. The softer *"Google hasn't verified this app"* warning is expected: click **Advanced → Go to … (unsafe) → Allow**.
+
+## Usage
+
+```bash
+health-agent steps                       # reconciled Fitbit/Pixel steps
+health-agent sleep
+health-agent exercise
+health-agent get body-fat --reconcile
+health-agent get sleep -w \
+  --filter 'sleep.interval.civil_end_time >= "2026-06-01"'
+health-agent profile
+health-agent raw 'users/me/dataTypes/steps/dataPoints'   # escape hatch
+```
+
+JSON goes to stdout, diagnostics to stderr — pipe to `jq` freely.
+
+## Data model notes
+
+- **Reconciled stream** (`--reconcile` / `-w`): deduped data matching what the Fitbit app shows. The plain list returns raw per-source data points.
+- **Third-party logs (Hevy, Strava, …)** arrive via **Health Connect** (`dataSource.platform == "HEALTH_CONNECT"`) and are **excluded from the reconciled/wearables stream**. For workouts, use the plain `health-agent get exercise` (not `health-agent exercise`). Hevy stores the full set/rep/weight log as text in `.exercise.notes`.
+- Data type ids in the **path** are kebab-case (`body-fat`); in **filter** expressions they're snake_case (`body_fat`).
+- Source family for Fitbit/Pixel devices: `users/me/dataSourceFamilies/google-wearables`.
+- Full data type + scope reference: https://developers.google.com/health/scopes
+
+## Scopes requested by default (read-only)
+
+`activity_and_fitness`, `sleep`, `health_metrics_and_measurements`, `profile`.
+Override with `auth:setup --scopes "<space-separated full scope URLs>"`.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: health-agent
+description: Pull your own Fitbit / Pixel health data (steps, sleep, exercise, body metrics, profile) from the Google Health API via the `health-agent` CLI. Use when the user wants to read, export, summarize, or analyze their Fitbit/Google health data.
+homepage: https://developers.google.com/health
+metadata: {"openclaw":{"emoji":"❤️","requires":{"bins":["health-agent"],"env":[]}}}
+---
+
+# health-agent
+
+CLI wrapper around the **Google Health API** (the successor to the Fitbit Web API; legacy API sunsets September 2026). Authenticates with Google OAuth 2.0 and reads the caller's own health data.
+
+| Property | Value |
+|----------|-------|
+| **name** | health-agent |
+| **allowed-tools** | Bash(health-agent:*) |
+| **API base** | `https://health.googleapis.com/v4` |
+
+## ⚠️ Hard rules
+
+1. **Auth is required.** Every data command fails without valid credentials. Check with `health-agent auth:status` first.
+2. **This reads the authenticated user's OWN data only.** There is no way to pull someone else's data without their separate OAuth consent.
+3. **Output is JSON on stdout**, diagnostics on stderr — safe to pipe to `jq`.
+
+## First-time setup — agent onboarding playbook (human-in-the-loop)
+
+If `health-agent auth:status` shows `"configured": false` (or the command isn't on PATH yet), the user has never set this up. **Walk them through the steps below ONE AT A TIME** — give the exact URL for the current step, tell them what to click, then *wait for them to confirm before moving to the next step*. Do NOT paste all steps at once; this flow has subtle gotchas and users get lost in a wall of links. An agent **cannot** do the Google login or the consent click — those are the human's job. Everything else (install, `auth:setup`, reading data) the agent does.
+
+Why this is more involved than a typical CLI login: there is no public Google Health auth server, so the user must own their own Google Cloud OAuth client. This is a ~10-minute one-time setup.
+
+### Step 0 — Install the CLI if it doesn't exist (agent does this)
+If the `health-agent` command isn't on PATH, install it globally:
+```bash
+npm install -g health-agent
+# or
+pnpm install -g health-agent
+```
+npm package: https://www.npmjs.com/package/health-agent
+
+### Step 1 — Create / pick a Google Cloud project (user)
+→ https://console.cloud.google.com/projectcreate
+Name it e.g. `health-agent`, click **Create**, and make sure it's the **selected project** in the top bar for every step after this.
+
+### Step 2 — Enable the Google Health API (user)
+→ https://console.cloud.google.com/apis/library/health.googleapis.com
+Click **Enable**.
+
+### Step 3 — Configure the consent screen / Google Auth Platform (user)
+→ https://console.cloud.google.com/auth/audience
+- **NEW console gotcha:** if it says *"Google Auth Platform not configured yet"*, click **Get started** and complete the short wizard first: App name (anything) → User support email → Audience: **External** → Contact email → agree → **Create**.
+- Confirm **Publishing status = Testing** (do NOT publish — Testing mode skips the heavyweight restricted-scope verification review).
+- Under **Test users** → **+ Add users** → add the user's Google account → **Save**.
+- ⚠️ **The test-user account MUST be the exact same Google account whose Fitbit/Pixel data syncs**, and the same account they will sign in with at login. Ask the user which account their Fitbit/Pixel is tied to and confirm it matches.
+
+### Step 4 — Create the OAuth client (user)
+→ https://console.cloud.google.com/auth/clients  (in the new console, OAuth clients live here, NOT on the old `/apis/credentials` page)
+**+ Create client** → Application type: **Desktop app** → **Create**.
+- ⚠️ **It MUST be "Desktop app", NOT "Web application".** The CLI uses a `127.0.0.1` loopback redirect; a Web client without loopback redirects causes `redirect_uri_mismatch`. (Ignore any generic Google guide that says pick "Web Server".)
+- Copy the **Client ID** and **Client Secret** (or download the JSON).
+
+### Step 5 — Configure + log in (agent runs setup; user clicks Allow)
+```bash
+health-agent auth:setup --client-id <ID> --client-secret <SECRET>
+health-agent auth:login      # opens the browser
+health-agent auth:status     # verify "loggedIn": true
+```
+At the browser screen, tell the user to:
+1. Pick the **test-user account** from Step 3.
+2. On the **"Google hasn't verified this app"** warning (normal in Testing mode) → **Advanced** → **Go to health-agent (unsafe)**.
+3. Tick the scope boxes → **Allow**.
+
+`auth:login` runs a local loopback server and blocks until the user clicks Allow — run it in the background and watch its output for the `✅ Logged in` line, or have the user run it with a `! ` prefix.
+
+`auth:setup` writes `~/.health-agent/config.json`; `auth:login` writes `~/.health-agent/credentials.json`. Tokens auto-refresh. `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` env vars override stored config for headless use.
+
+### Setup troubleshooting (decision tree)
+- **"Access blocked: health-agent has not completed the Google verification process"** (hard block, no "Advanced" option) → the signing-in account is **not on the Test users list**, or publishing status isn't "Testing". Fix Step 3: add the exact account, Save, wait ~1 min, retry. Most common cause: signing in with a different account than the one added.
+- **"Google hasn't verified this app"** (soft warning with an Advanced link) → expected in Testing mode; click **Advanced → Go to … (unsafe) → Allow**.
+- **`redirect_uri_mismatch`** → the OAuth client is a "Web" type. Recreate it as **Desktop app** (Step 4).
+- **`invalid_grant` / refresh failed later on** → Testing-mode refresh tokens expire after **7 days**. Just re-run `health-agent auth:login`.
+- **`403` / scope error on a data command** → that data type's scope wasn't granted at consent. Re-run `auth:setup` with the right `--scopes`, then `auth:login`.
+
+## Reading data
+
+```bash
+# Convenience commands — default to the reconciled Fitbit/Pixel stream:
+health-agent steps
+health-agent sleep
+health-agent exercise
+
+# Any data type (kebab-case id): steps, sleep, exercise, body-fat, ...
+health-agent get steps --wearables --limit 50
+health-agent get body-fat --reconcile
+
+# Date filtering uses a Google Health filter string (field names are snake_case per data type):
+health-agent get sleep --wearables \
+  --filter 'sleep.interval.civil_end_time >= "2026-06-01"'
+
+# Profile and escape hatch for any v4 path:
+health-agent profile
+health-agent raw 'users/me/dataTypes/steps/dataPoints:dailyRollUp'
+```
+
+### Flags (data commands)
+- `--reconcile` — deduped stream (what the Fitbit app shows)
+- `--wearables` / `-w` — reconcile against `google-wearables` (Fitbit/Pixel) source
+- `--source <family>` — restrict to a data source family (implies reconcile)
+- `--filter <expr>` / `-f` — Google Health API filter expression
+- `--limit <n>` / `-n` — page size; `--page-token` — pagination
+
+## ⚠️ Third-party / Health Connect data (Hevy, Strava, etc.) — READ THIS for any workout question
+
+Data from third-party apps (e.g. **Hevy** strength logs, Strava, MyFitnessPal) reaches the Google Health API through **Health Connect**, NOT through the Fitbit cloud. These records have `dataSource.platform == "HEALTH_CONNECT"` and `dataSource.application.packageName` (e.g. `com.hevy`).
+
+**The reconciled/wearables stream EXCLUDES them.** `--reconcile`, `--wearables`/`-w`, and the convenience commands (`steps`/`sleep`/`exercise`) reconcile against the `google-wearables` (Fitbit/Pixel) source only, so Health Connect sessions are silently dropped.
+
+**Rule: when the user asks about workouts/training/exercise, ALWAYS query the plain (unreconciled) stream so third-party logs are included:**
+```bash
+health-agent get exercise -n 30          # NOT `health-agent exercise` (that one is wearables-only)
+```
+Then split by source to see everything:
+```bash
+# Third-party sessions (Hevy, Strava, …):
+health-agent get exercise -n 30 | jq '.dataPoints[] | select(.dataSource.platform=="HEALTH_CONNECT")'
+# Fitbit/Pixel auto-detected sessions:
+health-agent get exercise -n 30 | jq '.dataPoints[] | select(.dataSource.platform=="FITBIT")'
+```
+
+**The full set/rep/weight log is in `.exercise.notes`.** Hevy writes the entire workout (every exercise, set, kg × reps, plus a `hevy.com/workout/<id>` link) as plain text into the `notes` field. `metricsSummary`/`exerciseMetadata` are usually `{}` for these — don't conclude "no detail," read `notes`:
+```bash
+health-agent get exercise -n 30 | jq -r '.dataPoints[]
+  | select(.dataSource.application.packageName=="com.hevy")
+  | "\(.exercise.interval.startTime)  (\((.exercise.activeDuration|sub("s";"")|tonumber/60|floor)) min)\n\(.exercise.notes)\n"'
+```
+
+A single workout often appears **twice**: once as the third-party log (e.g. Hevy `STRENGTH_TRAINING`, rich `notes`, no biometrics) and once as the Fitbit band's overlapping auto-detected session (e.g. `CARDIO_WORKOUT`, has HR/zones, no set log). Cross-reference by overlapping time window to combine the set log with the heart-rate signature.
+
+## Install
+
+```bash
+cd ~/code/health-agent && npm install && npm run build && npm link
+# or run without linking: node ~/code/health-agent/dist/index.js <command>
+```
+
+## Troubleshooting
+For auth / setup errors (`invalid_grant`, `403` scope, `redirect_uri_mismatch`, "Access blocked", "Google hasn't verified this app") see the **Setup troubleshooting (decision tree)** at the end of the First-time setup playbook above.
+
+Data-command notes:
+- **Empty `dataPoints`** → no data in range, or the device hasn't synced. Widen the `--filter` window or confirm the Fitbit/Pixel app has synced recently.
+- **Exercise field names** → each session's activity is under `.exercise.exerciseType` (enum, e.g. `WALKING`) with a friendly `.exercise.displayName` (e.g. `Walk`); rich metrics live under `.exercise.metricsSummary` (calories, distance, steps, avg HR, active-zone minutes). There is no `activityType` field.
+- **`profile`** returns `age`, `membershipStartDate`, and configured walking/running stride lengths from `users/me/profile`.

package/dist/index.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+// src/auth.ts
+import http from "http";
+import crypto from "crypto";
+import { spawn } from "child_process";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { URL } from "url";
+var CONFIG_DIR = path.join(os.homedir(), ".health-agent");
+var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+var CREDS_FILE = path.join(CONFIG_DIR, "credentials.json");
+var AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
+var TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+var DEFAULT_SCOPES = [
+  "https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly",
+  "https://www.googleapis.com/auth/googlehealth.sleep.readonly",
+  "https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly",
+  "https://www.googleapis.com/auth/googlehealth.profile.readonly"
+];
+function ensureDir() {
+  if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+}
+function saveConfig(cfg) {
+  ensureDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 384 });
+}
+function loadConfig() {
+  const envId = process.env.GOOGLE_CLIENT_ID;
+  const envSecret = process.env.GOOGLE_CLIENT_SECRET;
+  if (envId && envSecret) {
+    return {
+      clientId: envId,
+      clientSecret: envSecret,
+      scopes: process.env.HEALTH_SCOPES?.split(/[ ,]+/).filter(Boolean) ?? DEFAULT_SCOPES
+    };
+  }
+  if (!fs.existsSync(CONFIG_FILE)) return null;
+  return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+}
+function saveCreds(creds) {
+  ensureDir();
+  fs.writeFileSync(CREDS_FILE, JSON.stringify(creds, null, 2), { mode: 384 });
+}
+function loadCreds() {
+  if (!fs.existsSync(CREDS_FILE)) return null;
+  return JSON.parse(fs.readFileSync(CREDS_FILE, "utf8"));
+}
+function clearCreds() {
+  if (fs.existsSync(CREDS_FILE)) fs.rmSync(CREDS_FILE);
+}
+function base64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  const args = process.platform === "win32" ? ["", url] : [url];
+  spawn(cmd, args, { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+}
+async function login() {
+  const config = loadConfig();
+  if (!config) {
+    throw new Error(
+      "No OAuth client configured. Run `health-agent auth:setup --client-id <id> --client-secret <secret>` first."
+    );
+  }
+  const verifier = base64url(crypto.randomBytes(32));
+  const challenge = base64url(crypto.createHash("sha256").update(verifier).digest());
+  const state = base64url(crypto.randomBytes(16));
+  const { code, redirectUri } = await new Promise(
+    (resolve, reject) => {
+      const server = http.createServer((req, res) => {
+        try {
+          const reqUrl = new URL(req.url ?? "/", "http://localhost");
+          if (reqUrl.pathname !== "/callback") {
+            res.writeHead(404).end();
+            return;
+          }
+          const returnedState = reqUrl.searchParams.get("state");
+          const err = reqUrl.searchParams.get("error");
+          const gotCode = reqUrl.searchParams.get("code");
+          res.writeHead(200, { "Content-Type": "text/html" });
+          if (err || !gotCode || returnedState !== state) {
+            res.end("<h2>Authorization failed.</h2><p>You can close this tab and check the terminal.</p>");
+            server.close();
+            reject(new Error(err ?? (returnedState !== state ? "state mismatch" : "no code returned")));
+            return;
+          }
+          res.end("<h2>\u2705 Connected.</h2><p>You can close this tab and return to the terminal.</p>");
+          server.close();
+          resolve({ code: gotCode, redirectUri: boundRedirectUri });
+        } catch (e) {
+          reject(e);
+        }
+      });
+      let boundRedirectUri = "";
+      server.listen(0, "127.0.0.1", () => {
+        const addr = server.address();
+        if (!addr || typeof addr === "string") {
+          reject(new Error("failed to bind local callback server"));
+          return;
+        }
+        boundRedirectUri = `http://127.0.0.1:${addr.port}/callback`;
+        const authUrl = new URL(AUTH_ENDPOINT);
+        authUrl.searchParams.set("client_id", config.clientId);
+        authUrl.searchParams.set("redirect_uri", boundRedirectUri);
+        authUrl.searchParams.set("response_type", "code");
+        authUrl.searchParams.set("scope", config.scopes.join(" "));
+        authUrl.searchParams.set("access_type", "offline");
+        authUrl.searchParams.set("prompt", "consent");
+        authUrl.searchParams.set("code_challenge", challenge);
+        authUrl.searchParams.set("code_challenge_method", "S256");
+        authUrl.searchParams.set("state", state);
+        console.error("\nOpening your browser to authorize the Google Health API\u2026");
+        console.error("If it does not open, paste this URL manually:\n");
+        console.error(authUrl.toString() + "\n");
+        openBrowser(authUrl.toString());
+      });
+      server.on("error", reject);
+    }
+  );
+  return exchangeCode(config, code, verifier, redirectUri);
+}
+async function exchangeCode(config, code, verifier, redirectUri) {
+  const body = new URLSearchParams({
+    code,
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    redirect_uri: redirectUri,
+    grant_type: "authorization_code",
+    code_verifier: verifier
+  });
+  const resp = await fetch(TOKEN_ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body
+  });
+  if (!resp.ok) {
+    throw new Error(`Token exchange failed (${resp.status}): ${await resp.text()}`);
+  }
+  const json = await resp.json();
+  const creds = {
+    accessToken: json.access_token,
+    refreshToken: json.refresh_token,
+    expiresAt: Date.now() + (json.expires_in ?? 3600) * 1e3,
+    scope: json.scope ?? config.scopes.join(" "),
+    tokenType: json.token_type ?? "Bearer"
+  };
+  saveCreds(creds);
+  return creds;
+}
+async function refresh(config, creds) {
+  if (!creds.refreshToken) {
+    throw new Error("Access token expired and no refresh token available. Run `health-agent auth:login` again.");
+  }
+  const body = new URLSearchParams({
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    refresh_token: creds.refreshToken,
+    grant_type: "refresh_token"
+  });
+  const resp = await fetch(TOKEN_ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body
+  });
+  if (!resp.ok) {
+    throw new Error(
+      `Token refresh failed (${resp.status}): ${await resp.text()}
+In OAuth "Testing" mode refresh tokens expire after 7 days \u2014 just run \`health-agent auth:login\` again.`
+    );
+  }
+  const json = await resp.json();
+  const updated = {
+    ...creds,
+    accessToken: json.access_token,
+    expiresAt: Date.now() + (json.expires_in ?? 3600) * 1e3,
+    scope: json.scope ?? creds.scope,
+    // Google does not return a new refresh_token on refresh; keep the old one.
+    refreshToken: json.refresh_token ?? creds.refreshToken
+  };
+  saveCreds(updated);
+  return updated;
+}
+async function getAccessToken() {
+  const config = loadConfig();
+  if (!config) throw new Error("Not configured. Run `health-agent auth:setup` first.");
+  let creds = loadCreds();
+  if (!creds) throw new Error("Not logged in. Run `health-agent auth:login` first.");
+  if (Date.now() >= creds.expiresAt - 6e4) {
+    creds = await refresh(config, creds);
+  }
+  return creds.accessToken;
+}
+
+// src/commands/auth.ts
+function authSetup(args) {
+  if (!args.clientId || !args.clientSecret) {
+    console.error("\u274C --client-id and --client-secret are required.");
+    console.error('   Create an OAuth "Desktop app" client in your Google Cloud project:');
+    console.error("   https://developers.google.com/health/setup");
+    process.exit(1);
+  }
+  const scopes = args.scopes ? args.scopes.split(/[ ,]+/).filter(Boolean) : DEFAULT_SCOPES;
+  saveConfig({ clientId: args.clientId, clientSecret: args.clientSecret, scopes });
+  console.error("\u2705 OAuth client saved to ~/.health-agent/config.json");
+  console.error(`   Scopes: ${scopes.length} requested.`);
+  console.error("   Next: health-agent auth:login");
+}
+async function authLogin() {
+  const config = loadConfig();
+  if (!config) {
+    console.error("\u274C Not configured. Run `health-agent auth:setup` first.");
+    process.exit(1);
+  }
+  try {
+    const creds = await login();
+    console.error("\n\u2705 Logged in. Token stored in ~/.health-agent/credentials.json");
+    console.error(`   Granted scopes: ${creds.scope}`);
+  } catch (e) {
+    console.error(`
+\u274C Login failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+function authStatus() {
+  const config = loadConfig();
+  const creds = loadCreds();
+  const status = {
+    configured: !!config,
+    clientId: config?.clientId ? config.clientId.replace(/(.{8}).*/, "$1\u2026") : null,
+    loggedIn: !!creds,
+    scope: creds?.scope ?? null,
+    expiresAt: creds ? new Date(creds.expiresAt).toISOString() : null,
+    expired: creds ? Date.now() >= creds.expiresAt : null,
+    hasRefreshToken: !!creds?.refreshToken
+  };
+  console.log(JSON.stringify(status, null, 2));
+}
+function authLogout() {
+  clearCreds();
+  console.error("\u2705 Credentials cleared (OAuth client config kept).");
+}
+
+// src/api.ts
+var BASE_URL = "https://health.googleapis.com/v4";
+var GOOGLE_WEARABLES = "users/me/dataSourceFamilies/google-wearables";
+async function authedGet(pathAndQuery) {
+  const token = await getAccessToken();
+  const url = `${BASE_URL}/${pathAndQuery}`;
+  const resp = await fetch(url, {
+    headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }
+  });
+  const text = await resp.text();
+  if (!resp.ok) {
+    throw new Error(`Google Health API ${resp.status} for ${url}
+${text}`);
+  }
+  return text ? JSON.parse(text) : {};
+}
+async function getDataPoints(dataType, opts = {}) {
+  const params = new URLSearchParams();
+  if (opts.filter) params.set("filter", opts.filter);
+  if (opts.limit) params.set("pageSize", String(opts.limit));
+  if (opts.pageToken) params.set("pageToken", opts.pageToken);
+  if (opts.reconcile && opts.dataSourceFamily) params.set("dataSourceFamily", opts.dataSourceFamily);
+  for (const [k, v] of Object.entries(opts.extra ?? {})) params.set(k, v);
+  const verb = opts.reconcile ? "dataPoints:reconcile" : "dataPoints";
+  const qs = params.toString();
+  return authedGet(`users/me/dataTypes/${dataType}/${verb}${qs ? `?${qs}` : ""}`);
+}
+async function rawGet(pathAndQuery) {
+  return authedGet(pathAndQuery.replace(/^\/+/, ""));
+}
+
+// src/commands/data.ts
+function toOpts(args) {
+  const reconcile = args.reconcile || args.wearables || !!args.source;
+  return {
+    reconcile,
+    dataSourceFamily: args.source ?? (args.wearables ? GOOGLE_WEARABLES : void 0),
+    filter: args.filter,
+    limit: args.limit,
+    pageToken: args.pageToken
+  };
+}
+function emit(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+async function getData(dataType, args) {
+  try {
+    emit(await getDataPoints(dataType, toOpts(args)));
+  } catch (e) {
+    console.error(`\u274C ${e.message}`);
+    process.exit(1);
+  }
+}
+async function getRaw(path2) {
+  try {
+    emit(await rawGet(path2));
+  } catch (e) {
+    console.error(`\u274C ${e.message}`);
+    process.exit(1);
+  }
+}
+async function getProfile() {
+  await getRaw("users/me/profile");
+}
+
+// src/index.ts
+var dataOpts = (y) => y.option("reconcile", {
+  describe: "Use the reconciled stream (deduped \u2014 matches what the Fitbit app shows)",
+  type: "boolean",
+  default: false
+}).option("wearables", {
+  alias: "w",
+  describe: "Shortcut for --reconcile against the google-wearables (Fitbit/Pixel) source",
+  type: "boolean",
+  default: false
+}).option("source", {
+  describe: "Restrict to a data source family (implies --reconcile), e.g. users/me/dataSourceFamilies/google-wearables",
+  type: "string"
+}).option("filter", {
+  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" });
+yargs(hideBin(process.argv)).scriptName("health-agent").usage("$0 <command> [options]").command(
+  "auth:setup",
+  "Store your Google Cloud OAuth client (Desktop app type)",
+  (y) => y.option("client-id", { describe: "OAuth client ID", type: "string" }).option("client-secret", { describe: "OAuth client secret", type: "string" }).option("scopes", { describe: "Space/comma separated scope override", type: "string" }),
+  (a) => authSetup({ clientId: a.clientId, clientSecret: a.clientSecret, scopes: a.scopes })
+).command("auth:login", "Authorize via browser and store tokens", {}, () => authLogin()).command("auth:status", "Show auth/config status (JSON)", {}, () => authStatus()).command("auth:logout", "Clear stored credentials", {}, () => authLogout()).command(
+  "get <dataType>",
+  "Fetch data points for any data type (e.g. steps, sleep, exercise, body-fat)",
+  (y) => dataOpts(
+    y.positional("dataType", {
+      describe: "Data type id (kebab-case), e.g. steps | sleep | exercise | body-fat",
+      type: "string"
+    })
+  ),
+  (a) => getData(a.dataType, {
+    reconcile: a.reconcile,
+    wearables: a.wearables,
+    source: a.source,
+    filter: a.filter,
+    limit: a.limit,
+    pageToken: a.pageToken
+  })
+).command(
+  "steps",
+  "Fetch step data (reconciled, Fitbit/Pixel)",
+  dataOpts,
+  (a) => getData("steps", { ...a, wearables: a.wearables || !a.reconcile && !a.source })
+).command(
+  "sleep",
+  "Fetch sleep data (reconciled, Fitbit/Pixel)",
+  dataOpts,
+  (a) => getData("sleep", { ...a, wearables: a.wearables || !a.reconcile && !a.source })
+).command(
+  "exercise",
+  "Fetch exercise/activity sessions (reconciled, Fitbit/Pixel)",
+  dataOpts,
+  (a) => getData("exercise", { ...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"',
+  (y) => y.positional("path", { describe: "Path after https://health.googleapis.com/v4/", type: "string" }),
+  (a) => getRaw(a.path)
+).demandCommand(1, "Run a command. Try `health-agent --help`.").strict().help().alias("h", "help").wrap(Math.min(120, process.stdout.columns ?? 120)).parse();

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "health-agent",
+  "version": "0.1.0",
+  "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"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "start": "node ./dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "fitbit",
+    "google-health",
+    "health",
+    "cli",
+    "ai-agent",
+    "oauth",
+    "quantified-self"
+  ],
+  "author": "Linh Phung",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codevagabond/health-agent.git"
+  },
+  "homepage": "https://github.com/codevagabond/health-agent#readme",
+  "bugs": {
+    "url": "https://github.com/codevagabond/health-agent/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.19",
+    "@types/yargs": "^17.0.32",
+    "tsup": "^8.5.1",
+    "typescript": "^5.3.3"
+  }
+}