> **Best experience:** Use the latest frontier model (GPT-5.4, Opus 4.6). This guide assumes a working [OpenClaw](https://docs.openclaw.ai) installation.
<p align="center">
<img src="bin/docs/images/turri-logo-badge.svg" alt="Turri logo" width="220" />
</p>
<h1 align="center">Turri</h1>
<p align="center"><strong>THE REAL HEALTH AGENT: 10 AI SPECIALISTS, ALL YOURS.</strong></p>
<p align="center">Turri brings 10 specialist agents to cross-analyze your sleep, meals, biomarkers, and activities, find hidden patterns, design science-based protocols, and run health self-experiments.</p>
<p align="center">Personal Health Agent by Compound · Works with Claude Code & OpenClaw</p>
<p align="center">
<a href="README.zh.md">中文文档</a> ·
<a href="#overview">Overview</a> ·
<a href="#how-it-works">How It Works</a> ·
<a href="#showcases">Showcases</a> ·
<a href="#quick-start">Quick Start</a> ·
<a href="#reference">Reference</a>
</p>
## Why This Exists
Most health apps are **trackers**. They record what you tell them and show you charts. They don't think. They don't connect the dots between your sleep, your diet, and your lab results. They don't read papers to figure out why your CRP is trending up.
Turri is different. It's an **agentic system**: a team of 10 specialized AI physicians that actively work on your health data.
| What exists today | What Turri does |
|---|---|
| Log meals manually | Logs meals from photos or text, estimates nutrients via deterministic catalog + USDA API, learns your recipes |
| See a weight chart | Detects that your weight drops faster on weeks with >150g protein/day AND >7h sleep |
| Track supplements in a spreadsheet | Flags interactions (NIH ODS), tracks compliance, aligns with active trials |
| Get generic health tips from AI chat | Searches PubMed & bioRxiv for evidence specific to YOUR data patterns |
| Read a health report and forget about it | Builds a persistent health profile that makes every recommendation more precise over time |
| Wonder if that thing you saw on Instagram actually works | Designs a controlled self-experiment, tracks execution, runs causal analysis — and says "not enough data" when there isn't |
<a id="overview"></a>
## Overview
Turri turns longitudinal health data and daily context into a health system you can query, inspect, and act on from a single agentic workflow.
- `/snap` — meal logging with ingredient-level nutrition enrichment
- `/health` — Whoop data import + structured health profile
- `/news` — curated health/longevity digest
- `/insights` — structured self-experiments with gap-aware recommendations
- `daily-coach` — cron-driven personalized daily coaching via 10 specialist subagents
- `health-qa` — interactive health Q&A that routes questions to relevant specialist subagents
All skills respond to natural language. Say "had salmon with rice for lunch" instead of `/snap`, or "how did I sleep?" instead of `/health`.
<a id="how-it-works"></a>
## How It Works
Turri combines OpenClaw skills, deterministic Python helpers, and local data stores so each interaction can stay inspectable while still feeling conversational.
### System Architecture
```mermaid
flowchart TB
subgraph User["👤 User Input"]
Photo["📸 Food Photo / Text"]
Whoop["⌚ Whoop Strap"]
QA["📝 Questionnaire"]
CI["✅ Check-in Data"]
end
subgraph Skills["Skill Layer"]
Snap["/snap"]
Health["/health"]
News["/news"]
Insights["/insights"]
Coach["daily-coach<br/>(cron 7:10am)"]
HealthQA["health-qa<br/>(interactive)"]
end
subgraph Tools["Tool Layer (index.ts)"]
TNutrition["nutrition"]
THealth["health_profile"]
TWhoop["whoop_import"]
TExperiments["experiments"]
TNews["news_digest"]
TCoach["coaching_context"]
end
subgraph Scripts["Script Layer (bin/)"]
EL["estimate_and_log.py"]
LK["lookup.py"]
IW["import_whoop.py"]
PS["profile_store.py"]
FD["fetch_digest.py"]
EX["experiments.py"]
DHC["daily_health_coach.py"]
end
subgraph Data["longevityOS-data/"]
Meals["nutrition/meals.csv"]
NCache["nutrition/nutrition_cache.json"]
Profile["health/profile.json"]
Tokens["health/whoop_tokens.json"]
Experiments["insights/experiments.json"]
Checkins["insights/checkins.json"]
NewsCache["news/cache.json"]
end
subgraph External["External APIs"]
WhoopAPI["Whoop API v2"]
RSS["RSS Feeds"]
end
Photo --> Snap --> TNutrition --> EL --> LK --> NCache
EL --> Meals
Whoop --> WhoopAPI
Health --> TWhoop --> IW --> WhoopAPI
Health --> THealth --> PS --> Profile
IW --> Tokens
QA --> Health
News --> TNews --> FD --> RSS
FD --> NewsCache
CI --> Insights --> TExperiments --> EX
EX --> Experiments
EX --> Checkins
Coach --> TCoach --> DHC
HealthQA --> TNutrition
HealthQA --> THealth
HealthQA --> TExperiments
HealthQA --> TNews
DHC --> Meals
DHC --> Profile
DHC --> Experiments
DHC --> Checkins
DHC --> NewsCache
```
### Whoop Integration
Whoop is the primary wearable data source today. Turri uses a one-time OAuth flow, stores tokens locally, and merges each sync into the structured health profile.
```mermaid
sequenceDiagram
participant U as User (Browser)
participant O as OAuth Server
participant W as Whoop API
participant S as import_whoop.py
participant P as profile.json
Note over U,W: One-time OAuth flow
U->>O: Visit /api/whoop/authorize
O->>W: Redirect to Whoop login
W-->>O: Callback with auth code
O->>W: Exchange code for tokens
W-->>O: access_token + refresh_token
O-->>U: "Copy Tokens for CLI"
U->>S: Paste tokens → whoop_tokens.json
Note over S,W: Each /health sync
S->>S: Read whoop_tokens.json
S->>W: GET /v2/recovery
W-->>S: score, RHR, HRV, SpO2, skin temp
S->>W: GET /v2/activity/sleep
W-->>S: stages, efficiency, respiratory rate
S->>W: GET /v2/cycle
W-->>S: strain (0-21), kJ, avg/max HR
S->>W: GET /v2/activity/workout
W-->>S: sport, HR zones, distance
S->>W: GET /v2/user/measurement/body
W-->>S: height, weight, max HR
S->>S: Normalize + aggregate
S->>P: Merge under "whoop" key
```
### Daily Coach — 10 Specialist Subagents
Every morning, the daily coach cron gathers context from all data stores and dispatches 10 specialist subagents in parallel. Each delivers its own Telegram bubble as it completes.
### The Specialists
<table>
<tr>
<td align="center" width="20%"><img src="bin/docs/characters/yuyi.svg" alt="Imperial Physician" width="80"/><br/><b>Imperial Physician</b><br/><sub>Orchestrator — synthesizes #1 priority</sub></td>
<td align="center" width="20%"><img src="bin/docs/characters/shiyi.svg" alt="Diet Physician" width="80"/><br/><b>Diet Physician</b><br/><sub>Nutrition — macros, micros, food suggestions</sub></td>
<td align="center" width="20%"><img src="bin/docs/characters/daoyin.svg" alt="Movement Master" width="80"/><br/><b>Movement Master</b><br/><sub>Exercise — strain-adjusted training</sub></td>
<td align="center" width="20%"><img src="bin/docs/characters/zhenmai.svg" alt="Pulse Reader" width="80"/><br/><b>Pulse Reader</b><br/><sub>Body Metrics — RHR, HRV, SpO₂ trends</sub></td>
<td align="center" width="20%"><img src="bin/docs/characters/yanfang.svg" alt="Formula Tester" width="80"/><br/><b>Formula Tester</b><br/><sub>Biomarkers — cross-domain patterns</sub></td>
</tr>
<tr>
<td align="center" width="20%"><img src="bin/docs/characters/bencao.svg" alt="Herbalist" width="80"/><br/><b>Herbalist</b><br/><sub>Supplements — micronutrient gap analysis</sub></td>
<td align="center" width="20%"><img src="bin/docs/characters/shixiao.svg" alt="Trial Monitor" width="80"/><br/><b>Trial Monitor</b><br/><sub>Experiments — compliance tracking</sub></td>
<td align="center" width="20%"><img src="bin/docs/characters/yuanpan.svg" alt="Court Magistrate" width="80"/><br/><b>Court Magistrate</b><br/><sub>Trial Design — N-of-1 candidates</sub></td>
<td align="center" width="20%"><img src="bin/docs/characters/yizheng.svg" alt="Medical Censor" width="80"/><br/><b>Medical Censor</b><br/><sub>Safety Review — overtraining, decline flags</sub></td>
<td align="center" width="20%"><img src="bin/docs/characters/baogao.svg" alt="Court Scribe" width="80"/><br/><b>Court Scribe</b><br/><sub>Reports — relevant research + literature</sub></td>
</tr>
</table>
### Dispatch Flow
<a id="showcases"></a>
## Showcases
Turri is designed to feel like a health operating system rather than a pile of separate trackers. These examples show how that experience comes together across coaching, nutrition, pattern detection, and biomarker review.
<details>
<summary>🏥 Daily Coach — 10 specialists review your data every morning</summary>
<p align="center">
<img src="bin/docs/images/telegram-mockup.png" alt="Daily Coach" width="390" />
</p>
</details>
<details>
<summary>🍚 Weekly Nutrition Review — macros, micros, and personalized food suggestions</summary>
<p align="center">
<img src="bin/docs/images/mockup-nutrition.png" alt="Nutrition Review" width="390" />
</p>
</details>
<details>
<summary>🔍 Pattern Detection — caffeine, sleep, and travel correlations</summary>
<p align="center">
<img src="bin/docs/images/mockup-patterns.png" alt="Pattern Detection" width="390" />
</p>
</details>
<details>
<summary>🧪 Blood Work Analysis — biomarker trends and optimization advice</summary>
<p align="center">
<img src="bin/docs/images/mockup-bloodwork.png" alt="Blood Work Analysis" width="390" />
</p>
</details>
<details>
<summary>🌙 Always On — late night chat, empathetic and human</summary>
<p align="center">
<img src="bin/docs/images/mockup-sleep.png" alt="Late Night Chat" width="390" />
</p>
</details>
<a id="quick-start"></a>
## Quick Start
If OpenClaw is already installed, this is the shortest way to get Turri running.
### Install on OpenClaw (Recommended)
Copy and paste the following commands into your OpenClaw chat session.
```bash
# **Install the skills and plugins:**
git clone https://github.com/compound-life-ai/Turri
cd Turri
npm install
openclaw plugins install -l .
# **Setup the daily cron jobs (replace <CHAT_ID> with your Telegram DM chat ID):**
openclaw cron add --name "Health Morning Brief" --cron "0 7 * * *" --tz "America/Los_Angeles" --session isolated --light-context --announce --best-effort-deliver --channel telegram --to "<CHAT_ID>" --message "Use the health and insights skills to create today's morning brief. Summarize yesterday's nutrition totals, the latest Apple Health sleep/activity context, 1-2 lifestyle recommendations, and include the active experiment check-in if relevant. Reply in the user's language and keep it compact."
openclaw cron add --name "Health News Digest" --cron "5 7 * * *" --tz "America/Los_Angeles" --session isolated --light-context --announce --best-effort-deliver --channel telegram --to "<CHAT_ID>" --message "Use the news skill to fetch today's curated digest. Summarize only the highest-signal items for nutrition, sleep, exercise, aging, and self-experimentation. Keep the message concise and mention the source for each item."
openclaw cron add --name "Daily Health Coach" --cron "10 7 * * *" --tz "America/Los_Angeles" --session isolated --light-context --announce --best-effort-deliver --channel telegram --to "<CHAT_ID>" --message "Use the daily-coach skill to generate today's personalized health coaching message. Keep it compact, conservative, and grounded in local health, nutrition, experiment, and cached-news context."
# Verify the plugin loaded correctly:
openclaw plugins doctor
openclaw plugins inspect compound-clawskill
# Start a **fresh OpenClaw session** after install — skills are snapshotted at session start.
# For the 10-subagent daily coach, add to `~/.openclaw/openclaw.json`:
{
agents: {
defaults: {
subagents: {
maxChildrenPerAgent: 10,
maxConcurrent: 10,
},
},
},
}
```
### Uninstall
```bash
openclaw plugins uninstall compound-clawskill
```
This removes the plugin registration. The cloned repository and any data in `longevityOS-data/` remain on disk.
To also remove cron jobs, find their IDs with `openclaw cron list`, then:
```bash
openclaw cron remove <job-id>
```
<a id="reference"></a>
## Reference
The sections below keep the full technical detail from the original README and are useful once you want to inspect the plugin boundary, local tooling, or repository structure.
### Plugin & SDK
This is a native [OpenClaw plugin](https://docs.openclaw.ai/plugins/building-plugins) that registers 8 tools via the [Plugin SDK](https://docs.openclaw.ai/plugins/sdk-overview):
| Tool | Description |
|------|-------------|
| `nutrition` | Log meals, daily totals, weekly summary vs RDA |
| `health_profile` | Merge questionnaire/Whoop data, show profile |
| `whoop_initiate` | First-time Whoop OAuth setup and token validation |
| `whoop_sync` | Fetch latest Whoop data and merge into profile |
| `experiments` | Create, check-in, analyze self-experiments |
| `news_digest` | Fetch ranked health/longevity news |
| `coaching_context` | Generate daily coaching context from all data |
| `learnings` | Search/log debugging discoveries, read trace logs |
Each tool wraps the corresponding Python script in `bin/` — the SDK entry point (`index.ts`) shells out to them via `execFile`.
Skills in top-level directories (`snap/`, `health/`, etc.) provide agent-facing guidance (when to use each tool, how to present results). The tools provide the typed, inspectable interface that OpenClaw registers.
**Relevant OpenClaw docs:**
- [Plugin SDK Overview](https://docs.openclaw.ai/plugins/sdk-overview)
- [Plugin Entry Points](https://docs.openclaw.ai/plugins/sdk-entrypoints)
- [Plugin Manifest](https://docs.openclaw.ai/plugins/manifest)
- [Plugin Architecture](https://docs.openclaw.ai/plugins/architecture)
- [Plugin Setup & Config](https://docs.openclaw.ai/plugins/sdk-setup)
- [Plugin Testing](https://docs.openclaw.ai/plugins/sdk-testing)
### Development
```bash
# Run Python tests
python3 -m unittest discover -s bin/tests -v
# Install Node dependencies before linking the plugin
npm install
# Link plugin for local development
openclaw plugins install -l .
openclaw gateway restart
# Inspect registered tools
openclaw plugins inspect compound-clawskill
# Diagnostics
openclaw plugins doctor
```
If `openclaw plugins doctor` warns that `plugins.allow is empty`, that is a separate trust warning for non-bundled plugins. It does not mean the Turri install itself failed.
Tests use real (sanitized) Whoop API response fixtures from `bin/tests/fixtures/whoop/`.
### Repo Layout
```
index.ts SDK entry point — registers 8 tools + observability hooks
openclaw.plugin.json Plugin manifest (skills, config schema)
package.json Package metadata + openclaw extensions
skill.md Root meta skill (natural language routing + debugging guide)
snap/ Meal logging skill
health/ Health profile & Whoop skill
health-qa/ Health Q&A skill
insights/ Self-experiments skill
news/ Health news digest skill
daily-coach/ Cron-driven daily coaching skill
agents/ Specialist subagent prompts (10 files)
bin/ Scripts, tests, docs, seed data, cron configs
common/ Shared Python utilities (storage, paths, logging, learnings)
nutrition/ Meal logging & nutrient enrichment scripts
health/ Health profile & Whoop import scripts
insights/ Self-experiment scripts
news/ News digest scripts
coach/ Daily coaching context script
tests/ Unit tests + Whoop API fixtures
seed/ Bootstrap fixture data
cron/ Example cron job configs
docs/ Architecture and design notes
longevityOS-data/ Runtime data (gitignored)
website/ Next.js landing page
```
### Observability
All tool calls are traced through OpenClaw plugin hooks registered in `index.ts`. The trace captures five layers of the tool call pipeline — from what the LLM generated, through SDK processing, to script execution — enabling root cause diagnosis without reproducing the bug.
```
LLM generates tool call
|
Layer -1: llm_output .......... what the model generated
|
Layer 0: before_tool ......... what execute() received + auto-diff vs LLM
|
Layer 1: after_tool .......... result, error, duration + streak detection
|
Layer 2: script_io ........... internal script events (3 scripts)
|
Layer 3: artifact ............ preserved temp files on failure
```
Key features:
- **Cross-layer diffing** — auto-detects when the SDK mutates LLM-generated arguments (would have instantly solved the Bug #8 empty `input_json` issue)
- **Streak detection** — flags consecutive failures of the same tool
- **Session summaries** — one-line overview of all tool calls at session end
- **Evidence preservation** — temp files saved to `debug/artifacts/` on failure instead of being deleted
- **Learnings system** — persistent JSONL store where agents record debugging discoveries with confidence decay (observed/inferred lose 1pt per 30 days)
- **Agent debugging protocol** — `skill.md` instructs agents to search learnings before debugging, read trace logs, diagnose by layer, and log discoveries
Three scripts with hook blind spots have additional instrumentation: `estimate_and_log.py` (temp file + enrichment), `import_whoop.py` (token refresh + 5 API calls), `fetch_digest.py` (per-feed results). The other five scripts are sufficiently covered by hooks alone.
All logs go to `longevityOS-data/debug/` (gitignored, local-only). See [bin/docs/observability.md](bin/docs/observability.md) for the full guide with triangulation workflows and worked examples.
### Docs
- [bin/docs/observability.md](bin/docs/observability.md) — observability layers, triangulation, learnings system
- [bin/docs/install.md](bin/docs/install.md)
- [bin/docs/openclaw-extension-survey.md](bin/docs/openclaw-extension-survey.md)
- [bin/docs/proposed-health-companion-architecture.md](bin/docs/proposed-health-companion-architecture.md)
- [bin/docs/longevity-os-reference-notes.md](bin/docs/longevity-os-reference-notes.md)
- [bin/docs/news-sources.md](bin/docs/news-sources.md)