Weekly agent architecture insights + a free cheatsheet.
No spam. Unsubscribe anytime.
The Health Stack
Tier 3 · Real Build8 min read
The health stack is five interconnected pieces: a Garmin data pipeline, a daily recovery email, a web panel in the Nerve Center cockpit, a KB-backed health-expert agent, and a health_metrics Supabase table that ties them together. Each piece was built to fix a specific failure mode of the previous one.
The foundation is agents/health/garmin_morning_pull.py, which runs on a cron and pulls from JD’s Garmin Connect account. It writes workout sessions, sleep stages, resting heart rate, steps, and caloric burn into ~/clawd/domains/health/state/health.yaml (nested by date, under a top-level entries key).
One non-obvious fact surfaced during debugging: JD’s Garmin Venu (gen-1) does not report sleep scores, HRV, or training readiness via the live API. Those are Firstbeat features on Venu-2+. The pipeline computes a local sleep score from the raw stage data and labels HRV as “not reported” — an honest label rather than a silent null. The root cause was confirmed in CHANGELOG 2026-06-06.
A separate bug sat silent for weeks: sync_health_metrics() was trying to read three YAML files that did not exist (garmin.yaml, sleep.yaml, weight.yaml) while the actual data was landing in health.yaml. The health_metrics Supabase table was empty the whole time, and the cockpit dashboards showed nothing. The fix (CHANGELOG 2026-06-06 15:23) rewired the sync to read health.yaml’s nested shape, added a format-drift guard, and backfilled the two most recent days.
The Apple Health weight pipeline adds a second data source: an iOS Shortcut sends Arboleaf scale weight to the bridge endpoint, which writes to weight_log (with a health_metrics fallback). That pipeline went live via PRs #53 and #54 (CHANGELOG 2026-06-07).
agents/health/daily_health_email.py runs at 7 AM MT every day. It reads the previous night’s Garmin data and sends a Whoop/Oura-style recovery summary:
Sleep score (computed from stages, since the device doesn’t report one)
Sleep stage breakdown
Resting heart rate with a 7-day trend
Body battery reading
An honest HRV line (“not reported” on this device)
A green/yellow/red read-out at the top
The email is a forcing function. You can ignore a dashboard, but a 7 AM email is harder to skip.
/health in the Nerve Center cockpit (PR #172, merged 2026-06-06) reads from health_metrics and renders the same data in a web panel. The migration added body_battery columns. The panel is live at nerve-center-v5.vercel.app/health.
The panel exists because the email is ephemeral — once read, it’s gone. The panel keeps the 7-day trend visible when JD wants it.
agents/health_expert is where the stack becomes advisory rather than just reporting.
It was built (CHANGELOG 2026-06-08 21:31) as a KB-backed specialist that mirrors the professor agent’s architecture:
An 8-stream deep-research knowledge base (~180 KB cited, evidence-tiered: human studies, animal studies, X/Reddit anecdote)
A verbatim system prompt
JD’s goal file injected on every call
Retrieval uses synthesis + goals unconditionally, plus top-K topic files by keyword. The agent is reachable via python3.12 -m agents.health_expert or ask_agent health-expert. A weekly check-in cron fires Sunday at 8:10 AM.
The agent’s first real output was a cold audit of JD’s protocol. Findings (CHANGELOG 2026-06-08): the protocol was 30% self-sabotaging, under-eating protein was the number-one risk to the physique goal, and realistic competition prep was 14–18 months out. Goals were persisted to jd-fitness-goals.md and the memory layer.
Since then the agent has handled:
A master health plan (Mon/Tue/Thu/Fri upper/lower split + Wednesday cardio/yoga, peptide protocol redesign)
A reta/tesamorelin/ipamorelin stack with a daily shot timing table
Garmin workout auto-scheduling (32 occurrences live 8 weeks out)
A strict pull-up progression ladder from dead hangs to first unassisted rep
The peptide protocol work is a good example of evidence-tiering in practice. Every recommendation cites whether the evidence comes from a controlled human study, an animal study, or anecdote. The agent flags when GH-stack timing conflicts with another goal (reta and gastric emptying vs. GH shot timing) and proposes a resolution rather than ignoring the conflict.
The scheduler (agents/health/garmin_connect.py schedule command) auto-creates Garmin workouts programmatically. It reads JD’s master training plan, maps exercises to Garmin’s workout enums, and schedules 32 occurrences 8 weeks out — deduplicating against what’s already on the calendar.
The root-cause fix that made this accurate (CHANGELOG 2026-06-08): the workout push script was hardcoded, so edits to JD’s training plan never reached Garmin. The fix was to parse the master plan YAML as the single source of truth. New parser tests plus a live-plan regression guard (55 tests green) make sure the two stay in sync.
The Supabase table is the integration point. Anything that needs historical health data reads from there. The email and the panel are two views on the same data, not separate pipelines.
JD’s watch doesn’t return a sleep score. The pipeline computes one from stage data rather than returning null. Never show a user an empty field that could be approximated from what you have.
Fix silent data gaps before building features
The health panel and email were built while the Supabase table was quietly empty. The features existed but showed nothing. Root-cause the data pipeline first.
Evidence-tier your KB
Separate human controlled trials from animal studies from anecdote. A health agent that treats Reddit posts and peer-reviewed trials as equivalent is not reliable. The health-expert KB is explicit about source quality.
Mirror the professor architecture
Goal-file injection + synthesis + top-K topic retrieval is a reusable pattern. The health-expert and professor agents use the same shape. When you build a domain expert, start from that template.