health-sync
Skill2 starsChanged 8 months agoMITView on GitHub
Sync Fitbit health data to Supabase and local DuckDB — pull, backfill, check status, manage sync schedules
- Reads credentials
- Sends data out
1 other project uses a version of this.
Adopted by
Most recently taken up by
- tonydzi/second-brain-starter-kittheir own version, first seen Sep 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- tonydzi/second-brain-starter-kit★ 6same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- health-analysisSkill
- health-loggingSkill
- health-setupSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 9 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 84
Use --full on pull when:
- Distinctive: line 87
After fixing a sync issue that affected historical data
- Distinctive: line 109
Weight: Only populated if the user logs weight manually or has a Fitbit-connected scale.
- Very specific: line 170
Rate limit recovery: If you hit the limit, phf sync --days N replays the full window on re-run (safe because upserts are idempotent).
- Very specific: line 193
Create a plist to run phf pull on schedule.
- Distinctive: line 206
Check the error message:
- Distinctive: line 225
Check if the watch was worn that day (wear quality view):
- Distinctive: line 229
Check if Fitbit has the data (query API directly):
- Distinctive: line 233
If Fitbit has data but DB does not, trigger a manual sync for that domain.
- Distinctive: line 249
Do NOT retry multiple times rapidly — each failed attempt may consume the refresh token
- Very specific: line 250
Run phf auth --reauth to get a fresh token pair
- Distinctive: line 251
Verify no duplicate cron jobs or Edge Function invocations are running
- Distinctive: line 265
All syncs use idempotent upserts:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Health Sync Skill
This skill manages the data pipeline: Fitbit API to Supabase (cloud) to DuckDB (local). It covers syncing, backfilling, status checking, and troubleshooting sync failures.
Architecture Overview
Fitbit Web API
|
v
Supabase Edge Function (fitbit-sync) <-- Cloud, runs 4x/day via pg_cron
|
v
Supabase PostgreSQL (source of truth)
|
v
phf pull <-- Local, on demand or scheduled
|
v
DuckDB (data/health.duckdb) <-- Fast local analyticsCloud-first design: Supabase syncs 24/7 regardless of whether your laptop is open. The local DuckDB is a read-optimized cache that refreshes on demand.
How to Sync
Pull Latest Data (Supabase to Local DuckDB)
# Pull latest from Supabase into local DuckDB
phf pullThis is the most common operation. It pulls any new data from Supabase into your local DuckDB for fast querying by AI agents.
Trigger Cloud Sync (Fitbit to Supabase)
The cloud sync runs automatically 4x/day via pg_cron. To trigger it manually:
phf sync
# Via Edge Function directly (requires patient_id)
curl -s -X POST "$SUPABASE_URL/functions/v1/fitbit-sync" \
-H "Authorization: Bearer $SUPABASE_SERVICE_KEY" \
-H "Content-Type: application/json" \
-d '{"patient_id": "YOUR_PATIENT_UUID", "sync_all": true}'Sync a Single Domain
phf sync --domain heart_rate
# Via Edge Function
curl -s -X POST "$SUPABASE_URL/functions/v1/fitbit-sync" \
-H "Authorization: Bearer $SUPABASE_SERVICE_KEY" \
-H "Content-Type: application/json" \
-d '{"patient_id": "YOUR_PATIENT_UUID", "domains": ["heart_rate"]}'Backfill Historical Data
To sync more than the default 3 days:
phf sync --days 30 # Last 30 days, all domains
phf sync --days 90 # Last 90 days (may hit Fitbit rate limits)
phf sync --domain sleep --days 30 # Single domain, 30 daysThe --full flag only affects the pull step (Supabase → DuckDB), not the Fitbit fetch:
phf sync --days 30 --full # Fetch 30 days from Fitbit, then full re-pull to DuckDB
phf pull --full # Just re-pull everything from Supabase (no Fitbit fetch)Use --full on pull when:
- You suspect local DuckDB is out of sync with Supabase
- After schema changes
- After fixing a sync issue that affected historical data
The 10 Data Domains
Each domain corresponds to a Fitbit API endpoint and a database table:
| Domain | Table | What It Contains | API Endpoint |
activity | daily_activity | Steps, distance, floors, calories, active minutes, sedentary minutes | /1/user/-/activities/date/{date}.json |
heart_rate | daily_heart_rate | Resting HR, HR zone minutes and calories (out_of_range, fat_burn, cardio, peak) | /1/user/-/activities/heart/date/{date}/1d/1min.json |
sleep | daily_sleep | Sleep duration, efficiency, stages (deep, light, REM, wake), bed/wake times | /1.2/user/-/sleep/date/{date}.json |
hrv | daily_hrv | Heart rate variability — daily RMSSD and deep sleep RMSSD | /1/user/-/hrv/date/{date}.json |
spo2 | daily_spo2 | Blood oxygen saturation (avg, min, max) | /1/user/-/spo2/date/{date}.json |
breathing_rate | daily_breathing_rate | Breaths per minute during sleep stages | /1/user/-/br/date/{date}.json |
temperature | daily_temperature | Skin temperature deviation from baseline | /1/user/-/temp/skin/date/{date}.json |
cardio_score | daily_cardio_score | VO2 Max estimate (low and high range) | /1/user/-/cardioscore/date/{date}.json |
weight | daily_weight | Weight (kg), BMI, body fat % | /1/user/-/body/log/weight/date/{date}.json |
intraday_hr | intraday_heart_rate | Minute-by-minute heart rate (1440 readings/day max) | /1/user/-/activities/heart/date/{date}/1d/1min.json |
Known Data Gaps
- SpO2: Most Fitbit/Pixel Watch devices produce very few readings. Expect sparse data.
- Weight: Only populated if the user logs weight manually or has a Fitbit-connected scale.
- Temperature: Requires wearing the watch during sleep consistently.
How to Check Sync Status
phf statusVia Supabase Query
curl -s "$SUPABASE_URL/rest/v1/sync_checkpoints?select=domain,last_synced_date,last_run_at,status,error_message&order=domain" \
-H "apikey: $SUPABASE_SERVICE_KEY" -H "Authorization: Bearer $SUPABASE_SERVICE_KEY"Via DuckDB
import duckdb
con = duckdb.connect('data/health.duckdb', read_only=True)
print(con.sql("""
SELECT domain, last_synced_date, last_run_at, status, error_message
FROM sync_checkpoints ORDER BY domain
""").show())Freshness Check
To see how recent each domain's data is:
SELECT 'activity' as domain, max(date) as latest FROM daily_activity
UNION ALL SELECT 'heart_rate', max(date) FROM daily_heart_rate
UNION ALL SELECT 'sleep', max(date) FROM daily_sleep
UNION ALL SELECT 'hrv', max(date) FROM daily_hrv
UNION ALL SELECT 'spo2', max(date) FROM daily_spo2
UNION ALL SELECT 'breathing_rate', max(date) FROM daily_breathing_rate
UNION ALL SELECT 'temperature', max(date) FROM daily_temperature
UNION ALL SELECT 'cardio_score', max(date) FROM daily_cardio_score
UNION ALL SELECT 'weight', max(date) FROM daily_weight
UNION ALL SELECT 'intraday_hr', max(date(timestamp)) FROM intraday_heart_rate
ORDER BY domain;How to Backfill Historical Data
Initial Backfill (After First Setup)
The setup process typically syncs the last 30 days. For older data:
phf sync --days 90 # Last 90 days
phf sync --days 180 # Last 6 months
phf sync --days 365 # Last year (will hit rate limits — see below)Backfill Considerations
- Fitbit rate limit: 150 requests/hour. Each day-domain pair is one request. Backfilling 30 days x 10 domains = 300 requests = ~2 hours at max rate.
- Intraday HR is the largest: Each day produces up to 1,440 rows. A year of intraday = ~525,600 rows.
- Rate limit recovery: If you hit the limit,
phf sync --days Nreplays the full window on re-run (safe because upserts are idempotent). The cloud Edge Function uses checkpoint-based resume automatically. Just re-run after waiting an hour. - All writes are idempotent: Uses INSERT ON CONFLICT UPDATE (upsert), so re-running is safe.
Sync Schedule
Cloud Sync (pg_cron, Automatic)
By default, 4 sync times per day (computed from TIMEZONE in .env during setup):
| Local Time | Purpose |
| 06:00 | Morning — captures overnight sleep + HR |
| 12:00 | Midday — captures morning activity |
| 18:00 | Evening — captures afternoon data |
| 23:00 | Night — captures full day summary |
The actual UTC cron expressions depend on your timezone. Check cron.job in Supabase if you need exact times.
Local DuckDB Pull (User-Managed)
Options for keeping local DuckDB fresh:
macOS (launchd):
Create a plist to run phf pull on schedule.
Linux (cron):
0 7,12,18,23 * * * cd /path/to/project && phf pull >> data/logs/sync.log 2>&1Manual: Just run phf pull whenever you want fresh data before analysis.
Troubleshooting Sync Failures
Sync Status Shows "error"
Check the error message:
curl -s "$SUPABASE_URL/rest/v1/sync_checkpoints?status=eq.error&select=domain,error_message" \
-H "apikey: $SUPABASE_SERVICE_KEY" -H "Authorization: Bearer $SUPABASE_SERVICE_KEY"Common Sync Errors
| Error | Cause | Fix |
token_refresh_failed | Fitbit refresh token invalidated | Run phf auth --reauth |
rate_limit_exceeded | More than 150 requests/hour | Wait 1 hour, will auto-recover |
fitbit_api_500 | Fitbit servers temporarily down | Will auto-retry next scheduled run |
edge_function_timeout | Sync took >150s (large backfill) | Use CLI for backfills: phf sync --days N |
supabase_write_error | Database write failed | Check Supabase dashboard for DB status |
stale_data | Data not updating for a domain | Check if device is syncing to Fitbit app |
Data Missing for Specific Days
- Check if the watch was worn that day (wear quality view):
SELECT * FROM daily_wear_quality WHERE date = '2026-03-19' - Check if Fitbit has the data (query API directly):
phf sync --domain heart_rate --days 1 - If Fitbit has data but DB does not, trigger a manual sync for that domain.
DuckDB Out of Sync with Supabase
# Full re-pull from Supabase
phf pull --full
# Or single table
phf pull --table daily_heart_rateOAuth2 Token Safety
Fitbit refresh tokens are one-time-use. The system is designed so only one process touches the token at a time (single-dispatcher Edge Function). If you see token_refresh_failed:
- Do NOT retry multiple times rapidly — each failed attempt may consume the refresh token
- Run
phf auth --reauthto get a fresh token pair - Verify no duplicate cron jobs or Edge Function invocations are running
Data Flow Details
Incremental Sync (Default)
Each sync:
- Reads
last_synced_datefromsync_checkpointsfor each domain - Fetches data from
last_synced_dateto today - Upserts into the appropriate table (INSERT ON CONFLICT UPDATE)
- Updates
sync_checkpointswith new date and timestamp
Upsert Strategy
All syncs use idempotent upserts:
- Daily tables:
ON CONFLICT (patient_id, source, date) DO UPDATE - Sleep table:
ON CONFLICT (patient_id, source, log_id) DO UPDATE(supports multiple sleep entries per day) - Intraday HR:
ON CONFLICT (patient_id, source, timestamp) DO UPDATE
This means re-running a sync is always safe — it will not create duplicates.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

