# 💊 SupStack — Your AI Supplement Advisor

Turn your OpenClaw agent into an evidence-based supplement expert. Ask about any supplement, get safety checks, build personalized stacks, and stay up to date on new research — all through natural conversation on WhatsApp, Telegram, or any messaging platform your agent is connected to.

**225 supplements · 7,870+ studies · 27 health goals · Drug interaction checking · N-of-1 experiments · Timing optimiser · Proactive research alerts**

---

## What Can I Do With It?

Just message your agent like you'd ask a knowledgeable friend. Here's what real conversations look like:

### Ask about any supplement

> **You:** What's the deal with ashwagandha?
>
> **Agent:** **Ashwagandha** — Evidence: 7.5/10 (Strong) · 180 studies
>
> Adaptogenic herb with strong evidence for cortisol reduction and stress resilience. Also shows modest testosterone support in men.
>
> 📊 Evidence: 7.5/10 — 12 meta-analyses
> 💊 Dose: 300–600mg daily (KSM-66 or Sensoril extract)
> 🛡️ Safety: Moderate — cycle 8-12 weeks on, 2-4 weeks off. Avoid with thyroid conditions or pregnancy.
>
> Best for: stress reduction (96%), hormonal support (82%), sleep via stress pathway (78%)

### Get recommendations for your goals

> **You:** What should I take for better sleep and less anxiety?
>
> **Agent:** Top supplements for sleep + anxiety, ranked by evidence:
>
> 1. **Magnesium** (Evidence: 8.5, Match: 82) — GABA support + muscle relaxation. 200-400mg before bed.
> 2. **Ashwagandha** (Evidence: 7.5, Match: 76) — Cortisol reduction. 300-600mg, cycle every 8-12 weeks.
> 3. **L-Theanine** (Evidence: 7.0, Match: 71) — Alpha wave promotion, no sedation. 200mg as needed.
>
> 💡 Start with magnesium alone for 2 weeks before adding others.

### Check if your supplements are safe together

> **You:** Can I take magnesium with my ciprofloxacin prescription?
>
> **Agent:** 🔴 **Important interaction.** Magnesium reduces ciprofloxacin absorption by up to 90% through chelation. Separate them by at least 2 hours after or 6 hours before the antibiotic. Don't skip your antibiotic dose — just adjust timing.

### Get your full stack reviewed

> **You:** Analyze my stack: creatine, magnesium, vitamin D, omega-3, ashwagandha
>
> **Agent:**
> ✅ **Synergies:** Magnesium enhances vitamin D activation. Omega-3 + creatine support recovery through complementary mechanisms.
>
> ⚠️ **Flag:** Ashwagandha has a moderate safety rating — monitor thyroid if using long-term.
>
> 📊 **Coverage:** Strong on recovery, sleep, and stress. Gap in cognitive focus.
>
> 💡 **Consider adding:** L-Theanine or Lion's Mane for the focus gap — both synergize with your existing stack.

### Get smart recommendations that know your stack

> **You:** I already take magnesium and omega-3. What should I add for energy?
>
> **Agent:** Based on your current stack, here's what pairs best for energy:
>
> 1. **Creatine** (Score: 78) — Synergizes with both magnesium and omega-3. 5g daily, no cycling needed.
> 2. **Rhodiola Rosea** (Score: 64) — Energizing adaptogen, take mornings only. Complements magnesium's calming effect.
>
> Both avoid redundancy with what you already take.

### Stay updated on new research

> **You:** Keep me updated on any new studies related to my stack.
>
> **Agent:** Research Monitor is live! Tracking new studies for: 💪 Creatine · 🌙 Magnesium · ☀️ Vitamin D · 🐟 Omega-3
>
> I'll check weekly and message you when new research drops.

Then a week later, your agent messages you unprompted:

> **Agent:** 💊 **Research Update — March 2026**
>
> Checked 4 supplements. 2 new studies found:
>
> **Creatine** — New RCT (2026, n=200): Cognitive benefits confirmed in sleep-deprived adults at 5g/day. Supports your current dose.
>
> **Vitamin D** — Meta-analysis in The Lancet: 4000+ IU showed stronger immune outcomes than lower doses. You're already at the right level.
>
> Magnesium, Omega-3: no new studies this week.

### Track if a supplement works for you (N-of-1 Experiments)

> **You:** I just ordered magnesium for better sleep. Does it actually work?
>
> **Agent:** Magnesium has an 8.5/10 evidence score for sleep — one of the strongest.
>
> Want to test it properly? I can set up a 4-week experiment: baseline your sleep now, then check in weekly to measure if it's actually helping you.
>
> **You:** Sure, let's do it
>
> **Agent:** Quick baseline — 3 questions:
> 1. How long does it usually take you to fall asleep? (minutes)
> 2. Rate your sleep quality this past week (1-10)
> 3. How refreshed do you feel when you wake up? (1-10)
>
> **You:** About 45 minutes, sleep quality 4, freshness maybe 3
>
> **Agent:** Baseline recorded! Start tonight — 300-400mg magnesium glycinate, 30-60 min before bed. I'll check in next Monday.

One week later:

> **Agent:** Quick check-in on your Magnesium experiment (week 1/4):
> 1. How long to fall asleep this week?
> 2. Sleep quality (1-10)?
> 3. Morning freshness (1-10)?
>
> **You:** Down to about 30 min, quality 6, freshness 5
>
> **Agent:** Looking good! Sleep onset dropped 15 minutes and quality is up. Check-in 1/4 recorded — next one in 7 days.

After 4 weeks:

> **Agent:** Your magnesium experiment results are in!
>
> **Verdict: Clear Win** ✅
> • Sleep onset: 45 min → 22 min (−23 min) ✓
> • Sleep quality: 4 → 7.5 (+3.5 points) ✓
> • Morning freshness: 3 → 6 (+3 points) ✓
>
> Recommendation: Keep magnesium in your stack. Your personal results match the clinical evidence.

### Get your optimal timing schedule

> **You:** When should I take all my supplements?
>
> **Agent:** Based on your stack, here's your optimal timing:
>
> ☀️ **Morning (with breakfast)**
> • Creatine — 5g
> • Vitamin D3 — 4000 IU (needs fat for absorption)
> • Omega-3 — 2g (needs fat)
>
> 🌙 **Evening (30-60 min before bed)**
> • Magnesium Glycinate — 400mg
>
> ⚠️ Take Zinc 2+ hours away from Calcium if you add either.

### Export your stack for your doctor

> **You:** I have a doctor's appointment — can you export my supplement list?
>
> **Agent:** Here's your supplement stack summary:
>
> MY SUPPLEMENT STACK
> Generated February 20, 2026 — SupStack (supstack.me)
>
> Creatine — 5g daily (Evidence: 9/10, Safety: High)
> Magnesium Glycinate — 400mg at night (Evidence: 8.5/10, Safety: High)
> Vitamin D3 — 4000 IU morning (Evidence: 8/10, Safety: High)
> Omega-3 — 2g with meals (Evidence: 8/10, Safety: High)
>
> Want me to include your medications and health conditions too?

### Look up scientific terms

> **You:** What does bioavailability mean?
>
> **Agent:** **Bioavailability** — the percentage of a substance that enters your bloodstream and is available for your body to use. Higher bioavailability = better absorption. This is why magnesium glycinate (high bioavailability) is recommended over magnesium oxide (only ~4% absorbed).

### Compare supplements head to head

> **You:** Compare magnesium vs glycine for sleep
>
> **Agent:** Both are excellent for sleep with different mechanisms:
>
> | | Magnesium | Glycine |
> |---|---|---|
> | Evidence | 8.5/10 | 7.0/10 |
> | Mechanism | GABA support, muscle relaxation | Core temperature reduction |
> | Dose | 200-400mg | 3g |
> | Onset | 1-2 weeks | 1-3 days |
> | Safety | Excellent | Excellent |
>
> They actually stack well together — different pathways, complementary effects. Many people take both.

### It learns as you go

> **You:** I currently take creatine 5g, magnesium glycinate 300mg at night, vitamin D 4000 IU, and omega-3 2g.
>
> **Agent:** Got it — I've saved your stack. From now on when you say "my stack" I'll know what you're taking. I can run a full analysis, suggest additions, or check interactions anytime.

Two weeks later:

> **You:** My doctor just put me on atorvastatin. Is my stack still okay?
>
> **Agent:** I've checked atorvastatin against your stack:
>
> 🟡 **Omega-3** — at high doses (>3g) omega-3 may enhance atorvastatin's lipid effects. At your 2g dose, this is actually synergistic. No action needed.
>
> 🟢 Creatine, Magnesium, Vitamin D — no interactions with atorvastatin.
>
> I've added atorvastatin to your medications — I'll check against it automatically if you add new supplements.

---

## First Time Experience

The first time you ask your agent a supplement question, it answers your question first and then introduces itself:

> **You:** Is magnesium good for sleep?
>
> **Agent:** **Magnesium** — 8.5/10 evidence (Strong) · 400 studies
>
> Yeah, magnesium is one of the best things you can take for sleep. It works through your GABA receptors (basically your brain's chill-out system) and relaxes your muscles. Take 300-400mg of the glycinate form about an hour before bed.
>
> ---
>
> By the way — first time chatting supplements! I'm backed by **SupStack**, a database of 225 supplements scored by evidence quality from 7,870+ peer-reviewed studies.
>
> Here's what I'm good at:
>
> 💊 **Deep dives** — evidence, dosing, safety, how things actually work
> 🎯 **Recommendations** — tell me your goals and I'll match you with what the science supports
> 🛡️ **Safety checks** — drug interactions, combos, contraindications
> 📊 **Stack reviews** — share what you take and I'll find synergies, gaps, and concerns
> 🧪 **Experiments** — test if something actually works for *you* with structured tracking
> 🔬 **Research alerts** — I can watch for new studies on your stack and ping you
>
> I score evidence 0-10 and I'll always be upfront about how strong (or weak) the science is. I'm not a doctor — I help you understand the research. And I remember everything you tell me, so you never have to repeat yourself.
>
> What are you curious about?

After that first time, the intro won't appear again — the agent just answers your questions directly. You can always say **"what can you do?"** to see the intro again.

---

## Install

**Step 1:** Make sure jq is installed (one-time setup):

```bash
brew install jq
```

**Step 2:** Download and unzip the skill, then move it to your OpenClaw skills folder:

```bash
unzip supstack-skill-api.zip -d ~/.openclaw/skills/
mv ~/.openclaw/skills/supstack-skill ~/.openclaw/skills/supstack
```

**Step 3:** Verify it works:

```bash
bash ~/.openclaw/skills/supstack/scripts/supstack.sh search magnesium
```

You should see JSON results. If so, the skill is ready — just message your agent.

No API key needed. The SupStack database is free and public.

---

## Things You Can Say

The skill understands natural language. Here are phrases that activate it:

**Learning about supplements:**
- "Tell me about [supplement]"
- "What's the evidence for [supplement]?"
- "How do I take [supplement]? What form, what dose?"
- "What are the side effects of [supplement]?"
- "What does [scientific term] mean?"

**Getting recommendations:**
- "What should I take for [sleep / focus / energy / anxiety / recovery]?"
- "Best supplements for [goal]?"
- "I want to [improve sleep / reduce stress / build muscle] — what helps?"

**Safety and interactions:**
- "Is [supplement] safe?"
- "Can I take [supplement] with [medication]?"
- "Can I combine [supplement A] and [supplement B]?"
- "I'm on [medication] — what should I avoid?"

**Stack building and analysis:**
- "I take [X, Y, Z]. What should I add?"
- "Analyze my stack: [list of supplements]"
- "What pairs well with [supplement]?"
- "Compare [X] vs [Y]"

**Research tracking:**
- "Keep me updated on research for my stack"
- "Any new studies on [supplement]?"
- "Track studies on [supplement list]"
- "Stop research updates"

**Experiments (test if it works for you):**
- "Does [supplement] actually work?"
- "I want to try [supplement] — can we track my progress?"
- "Set up an experiment for [supplement] for [goal]"
- "How's my experiment going?"

**Timing & scheduling:**
- "When should I take my supplements?"
- "Optimize my timing schedule"
- "Can I take X and Y at the same time?"

**Stack export:**
- "Export my supplements for my doctor"
- "Give me a summary of what I take"
- "I need to share my stack with my healthcare provider"

**Your profile (it remembers so you don't have to):**
- "I currently take [supplement list]"
- "I'm on [medication] for [condition]"
- "My goal is [sleep / focus / energy]"
- "I stopped taking [supplement] because [reason]"
- "What's in my profile?" / "What do you know about me?"

---

## Research Monitor

The Research Monitor automatically checks for new studies on your supplements and messages you when something interesting is published.

**Start it:** Tell your agent "keep me updated on research for my stack" or "track new studies on magnesium, creatine, and vitamin D."

**What it does:**
- Checks for new studies on a schedule you choose (weekly, biweekly, or monthly)
- Messages you only when new research is found — no "nothing new" spam
- Remembers what it's already told you so you never see duplicates
- You can add or remove supplements from tracking at any time

**Change it anytime:**
- "Add ashwagandha to my research tracking"
- "Remove creatine from research tracking"
- "Stop all research updates"

**Enable automatic scheduling:** Copy the cron template to your OpenClaw jobs:

```bash
cat ~/.openclaw/skills/supstack/cron/research-monitor.json
# Then merge into ~/.openclaw/workspace/cron/jobs.json
```

---

## It Remembers You

The agent builds a profile as you talk. Mention your stack, medications, goals, or health conditions — it saves them and uses them automatically going forward.

> **You:** I'm currently taking magnesium glycinate 300mg at night, creatine 5g, vitamin D 4000 IU, and omega-3 2g.

From that point on, when you say "analyze my stack" or "what should I add?", the agent already knows what you take. No need to list everything again.

**What it remembers:**
- 💊 Your current supplements (names, doses, timing)
- 💉 Your medications (for automatic interaction checking)
- 🎯 Your health goals (so recommendations are personalized)
- 🚫 Your conditions and allergies (factored into safety)
- 📝 Supplements you've tried and stopped (and why)
- 🔍 Supplements you've asked about but aren't taking yet
- ⚙️ Your preferences (budget, pill count, capsule vs powder)

It also notices patterns. If you keep asking about sleep-related supplements, it'll pick up on that:

> **Agent:** I've noticed most of your questions lately are sleep-related. Want me to do a dedicated sleep stack analysis?

And if you've been researching something for a while without starting it:

> **Agent:** You've asked about lion's mane three times now. Want me to do a full breakdown — evidence, dosing, and how it fits with your current stack?

**What you can ask:**
- "What's my current stack?"
- "What medications do I have on file?"
- "I stopped taking ashwagandha — it gave me stomach issues" (moves it to past trials)
- "I just started metformin" (saves it and immediately checks against your stack)

---

## Safety Watchdog

The agent doesn't wait for you to ask about safety — it catches things proactively.

> **You:** Quick question about creatine timing. Oh also, my doctor put me on ciprofloxacin for a UTI.
>
> **Agent:** [answers creatine timing question]
>
> By the way — I noticed you mentioned ciprofloxacin. Let me check against your stack.
>
> 🔴 **Magnesium** — ciprofloxacin absorption is reduced by up to 90% when taken with magnesium. Separate them by at least 2 hours after or 6 hours before the antibiotic.
>
> 🟢 Creatine, Vitamin D, Omega-3 — no known interactions.
>
> I've added ciprofloxacin to your medications so I'll track this going forward.

**It watches for:**
- New prescriptions ("my doctor prescribed...", "I'm starting...")
- Life changes ("I'm pregnant", "I have surgery coming up")
- New diagnoses ("I was diagnosed with...", "turns out I have...")
- Medication changes ("I stopped my...", "changed my dose")

You don't need to do anything to enable this — it's always on once the skill is installed.

---

## Works Offline Too

If the SupStack API is temporarily unreachable, the agent doesn't just give up:

- It tells you clearly that the database is unavailable
- It falls back to general supplement knowledge for basic questions
- Your profile, stack, and medications are all stored locally — nothing is lost
- It clearly labels any answer from general knowledge vs the scored database
- Once the API is back, it seamlessly resumes using the full database

---

## What's In The Database

- **225 supplements** — vitamins, minerals, amino acids, botanicals, mushrooms, compounds, enzymes, fatty acids, probiotics
- **7,870+ peer-reviewed studies** — RCTs, meta-analyses, systematic reviews with key findings
- **27 health goals** organized into 7 categories:

| Sleep | Performance | Mental | Health |
|-------|------------|--------|--------|
| Fall asleep faster | Build strength | Sharpen focus | Reduce inflammation |
| Stay asleep | Improve endurance | Improve memory | Immune support |
| Deep sleep quality | Speed recovery | Reduce anxiety | Longevity |
| Fix sleep schedule | Boost energy | Support mood | |

- **Evidence scoring** from 0-10: Very Strong (8-10), Strong (6-8), Moderate (4-6), Emerging (0-4)
- **Safety ratings:** High (safe for most), Moderate (some cautions), Caution (always flagged)
- **Drug interactions** with severity levels and specific timing recommendations
- **80+ scientific definitions** for supplement terminology

---

## Troubleshooting

**Agent doesn't seem to use the skill?**
- Make sure the skill folder is at `~/.openclaw/skills/supstack/` (with `SKILL.md` inside)
- Restart your OpenClaw instance
- If you use skill allowlisting, add `supstack` to your `openclaw.json`:
  ```json
  { "skills": { "entries": { "supstack": { "enabled": true } } } }
  ```

**Getting "jq not found" errors?**
- Run `brew install jq`

**Research Monitor not sending updates?**
- Check that the cron job is in your `jobs.json`
- Run `bash ~/.openclaw/skills/supstack/scripts/supstack.sh monitor-status` to verify setup
- Run a manual check: `bash ~/.openclaw/skills/supstack/scripts/supstack.sh monitor-check`

---

## For Developers

Full API documentation is in `API.md`. The SupStack API is public at `https://supstack.me/api/v1` — 15 endpoints, all GET, no authentication required.

The skill script (`scripts/supstack.sh`) wraps every API endpoint. Run `bash scripts/supstack.sh help` for the full command reference.

State files are stored in `~/.openclaw/workspace/supstack/`:
- `profile.md` — user profile (stack, medications, goals, conditions, preferences)
- `monitor.json` — Research Monitor tracking state
- `experiments/*.json` — N-of-1 experiment data (one file per experiment)
- `onboarded` — first-run marker

---

**Built on the [SupStack](https://supstack.me) evidence database.**

Skill structure: MIT · Database content: © SupStack