VitalClaw

Health Data Aggregator SDK — ElizaOS plugin for wearable health data, vitals monitoring, and wellness insights.

npm install @vitalclaw/sdk

What is VitalClaw?

VitalClaw aggregates health data from wearable devices and manual entries into a unified, queryable data layer. It computes wellness scores, tracks trends, triggers alerts on anomalies, and exports data in FHIR R4 format.

Built as an ElizaOS plugin, VitalClaw turns any ElizaOS agent into a health-aware companion that can answer questions about vitals, present daily/weekly summaries, and monitor health goals.

Quick Start

import { VitalClawEngine, createVitalClawPlugin } from "@vitalclaw/sdk";

// Standalone usage
const engine = new VitalClawEngine({
  userId: "user-001",
  providers: [],
});

engine.ingest([
  { id: "1", userId: "user-001", metric: "heart_rate", value: 72, unit: "bpm", timestamp: new Date().toISOString(), source: "manual" },
  { id: "2", userId: "user-001", metric: "steps", value: 8432, unit: "steps", timestamp: new Date().toISOString(), source: "manual" },
]);

const summary = engine.getDailySummary();
console.log(`Wellness Score: ${summary.wellnessScore}/100`);

// ElizaOS plugin usage
const plugin = createVitalClawPlugin({ userId: "user-001", providers: [] });
// Add to your ElizaOS agent's plugin list

Architecture

┌─────────────────────────────────────────────────┐
│                  ElizaOS Agent                   │
│  ┌─────────────────────────────────────────────┐│
│  │           plugin-vitalclaw                   ││
│  │  Actions │ Providers │ Evaluators            ││
│  └────────────────┬────────────────────────────┘│
└───────────────────┼──────────────────────────────┘
                    │
┌───────────────────┼──────────────────────────────┐
│            VitalClaw Engine                       │
│  ┌────────┐ ┌──────────┐ ┌─────────┐ ┌────────┐ │
│  │  Store  │ │  Alert   │ │  Trend  │ │Summary │ │
│  │        │ │  Engine  │ │Analyzer │ │Builder │ │
│  └────┬───┘ └────┬─────┘ └────┬────┘ └───┬────┘ │
└───────┼──────────┼────────────┼───────────┼──────┘
        │          │            │           │
┌───────┼──────────┼────────────┼───────────┼──────┐
│       │    Provider Adapters  │           │      │
│ ┌─────┴──┐ ┌──────┐ ┌───────┐ ┌──────┐ ┌┴────┐ │
│ │ Fitbit │ │Garmin│ │Withings│ │ Oura │ │FHIR │ │
│ └────────┘ └──────┘ └───────┘ └──────┘ └─────┘ │
└──────────────────────────────────────────────────┘

Features

Data Aggregation — Unified data model for 24+ health metrics from 7+ wearable providers.

Wellness Scoring — Composite 0-100 score computed from cardiac, activity, sleep, stress, and body composition data.

Alert Engine — Configurable threshold alerts with severity levels. Ships with defaults for heart rate, blood oxygen, blood glucose, and body temperature.

Trend Analysis — Linear regression-based trend detection over 7/14/30/90 day periods. Classifies as improving, stable, declining, or insufficient data.

FHIR R4 Interop — Convert between VitalClaw data points and FHIR Observations using LOINC codes. Export as FHIR Bundles for healthcare system integration.

ElizaOS Plugin — Drop-in plugin with 6 actions, 1 context provider, and 1 safety evaluator. Includes 3 pre-built character templates.

Privacy-First — Configurable data retention, anonymized exports, and consent-based sharing.

Supported Providers

| Provider | Metrics | Auth | |----------|---------|------| | Fitbit | HR, HRV, SpO2, steps, sleep, weight, temp, respiratory | OAuth 2.0 | | Garmin | HR, HRV, SpO2, steps, sleep, stress, weight, VO2 max | OAuth 2.0 | | Withings | HR, BP, SpO2, weight, body fat, temp, sleep, ECG | OAuth 2.0 | | Apple Health | HR, HRV, BP, glucose, temp, steps, sleep, ECG, VO2 max | Export/bridge | | Google Fit | HR, steps, sleep, weight, BP, glucose, SpO2, temp | OAuth 2.0 | | Oura Ring | HR, HRV, SpO2, temp, respiratory, sleep, stress, steps | OAuth 2.0 | | Manual | HR, BP, SpO2, glucose, weight, temp, sleep, steps | — |

Supported Metrics (24)

Cardiac: heart_rate, resting_heart_rate, heart_rate_variability, blood_pressure, blood_oxygen, ecg, vo2_max

Activity: steps, distance, calories_burned, active_minutes, floors_climbed

Sleep: sleep_duration, sleep_stages, sleep_score

Body: body_weight, body_fat, bmi, body_temperature

Respiratory: respiratory_rate

Stress: stress_level

Metabolic: blood_glucose, hydration

Reproductive: menstrual_cycle

ElizaOS Plugin

Actions

| Action | Triggers | Description | |--------|----------|-------------| | CHECK_VITALS | "check my vitals", "health status" | Latest vital signs with wellness score | | DAILY_HEALTH_SUMMARY | "daily summary", "today's health" | Full daily report by category | | WEEKLY_HEALTH_SUMMARY | "weekly summary", "how was my week" | Weekly report with trends and insights | | LOG_VITALS | "log blood pressure 120/80", "log weight 74" | Parse and record manual measurements | | HEALTH_TRENDS | "show my trends", "am I improving" | Trend analysis over configurable periods | | SET_HEALTH_ALERT | "alert me if heart rate goes above 100" | Custom alert rule creation |

Characters

Three pre-built agent personalities:

• Vita — General health companion. Calm, precise, covers all metrics.
• Rex — Fitness coach. Energetic, focuses on activity and performance.
• Luna — Sleep analyst. Gentle, focuses on sleep quality and hygiene.

Safety Evaluator

Every response passes through a safety evaluator that flags potential medical diagnoses or treatment recommendations. The agent is instructed to present data, not practice medicine.

API Reference

VitalClawEngine

const engine = new VitalClawEngine(config);

// Ingest
engine.ingest(dataPoints)              // → HealthAlert[]

// Query
engine.query({ userId, metrics, from, to })  // → VitalDataPoint[]
engine.aggregate({ ..., groupBy, aggregation }) // → { period, value }[]
engine.getLatest("heart_rate")         // → VitalDataPoint | undefined

// Summaries
engine.getDailySummary(date?)          // → DailySummary
engine.getWeeklySummary(weekStart?)    // → WeeklySummary

// Trends
engine.getTrends("7d", metrics?)       // → TrendAnalysis

// Alerts
engine.getAlerts(unacknowledgedOnly?)  // → HealthAlert[]
engine.acknowledgeAlert(alertId)
engine.addAlertRule(rule)

// Events
engine.events.on("alert:triggered", handler)
engine.events.on("data:ingested", handler)
engine.events.on("goal:achieved", handler)

FHIRConverter

const fhir = new FHIRConverter();

fhir.toObservation(dataPoint)          // → FHIRObservation
fhir.fromObservation(observation)      // → VitalDataPoint
fhir.toBundle(dataPoints)              // → FHIR Bundle
fhir.getSupportedCodes()               // → { metric, loinc, display }[]

Disclaimer

VitalClaw is a health data aggregation tool. It does not provide medical advice, diagnoses, or treatment recommendations. Always consult qualified healthcare professionals for medical concerns. Data from consumer wearable devices may not be clinically validated.

License

MIT