AI-Powered Supplement & Medication Interaction Checker is a next-generation command-line tool and plugin ecosystem that analyzes the complex interplay between vitamins, dietary supplements, OTC medications, and prescription drugs. Inspired by the vitamin-analyzer concept but reimagined as a comprehensive interaction safety engine, this repository provides healthcare professionals, researchers, and informed consumers with evidence-based risk assessment, synergy detection, and personalized recommendations.
Unlike simple supplement trackers, this system acts as a pharmacological cartographer โ mapping the hidden pathways where nutrients and drugs collide, compete, or collaborate. It combines large language model reasoning (Claude, GPT-4) with authoritative biomedical databases to deliver clinically relevant insights.
Think of supplement regimens as chemical ecosystems. A single vitamin can act as a catalyst, an inhibitor, or a bystander depending on its molecular neighbors. This tool visualizes those relationships not as static warnings but as dynamic interaction landscapes โ a living atlas of your personal biochemistry.
- Key Features
- System Architecture
- Quick Start
- Configuration Guide
- Console Invocation
- Compatibility Matrix
- API Integration
- Multilingual Support
- Responsive UI
- 24/7 Customer Support
- Example Use Cases
- License
- Disclaimer
Every interaction report cites multiple authoritative sources: NIH Office of Dietary Supplements (ODS), PubMed Central, Cochrane Library, and the Korea Food & Drug Administration (KFDA). The system enforces a citation-first architecture โ no claim is made without a verifiable source.
Install the analyzer as a Claude Code plugin using the vitamin-analyzer@kemy-ai syntax. The /vitamin command instantly invokes a full interaction audit for any supplement/drug combination.
Enter any combination of supplements, medications, or compounds. The engine returns:
- Red-flag contraindications (dangerous combinations)
- Green-light synergies (beneficial pairings)
- Gray-zone uncertainties (insufficient evidence)
- Metabolic pathway overlaps (shared CYP450 enzyme competition)
| Database | Coverage | Update Frequency |
|---|---|---|
| NIH ODS | All vitamins/minerals | Quarterly (2026) |
| PubMed Central | 35M+ biomedical articles | Daily |
| Cochrane Reviews | 8,000+ systematic reviews | Monthly |
| KFDA API | Korean market OTC/Rx | Bi-monthly |
Claude API and OpenAI GPT-4 serve as the cognitive backbone. They:
- Parse ambiguous user queries ("Is my magnesium interacting with this antibiotic?")
- Synthesize conflicting evidence into nuanced recommendations
- Generate human-readable explanations with confidence scores
graph TD
A[User Input: Drug/Supplement Names] --> B{AI Parser}
B --> C[Active Ingredient Extractor]
C --> D[Database Query Layer]
D --> E[NIH ODS]
D --> F[PubMed]
D --> G[Cochrane]
D --> H[KFDA API]
E --> I[Interaction Matrix Builder]
F --> I
G --> I
H --> I
I --> J[Confidence Scorer]
J --> K[LLM Reasoning - Claude/GPT-4]
K --> L[Risk Level Classification]
L --> M{Severity Check}
M -->|Critical| N[Red Alert + Emergency Citation]
M -->|Moderate| O[Yellow Warning + Suggested Action]
M -->|Low| P[Green Advisory + Research Notes]
N --> Q[Formatted Report Output]
O --> Q
P --> Q
Q --> R[Console/Terminal Display]
Q --> S[Plugin Integration API]
The most direct path for Claude Code users:
/plugin install vitamin-analyzer@kemy-aiAfter installation, invoke with:
/vitamin --analyze "Vitamin D 5000 IU + Atorvastatin 10mg"For developers and non-Claude environments:
- Clone the repository (see download badge above)
- Install dependencies
- Configure API keys (see below)
Create a file named vitamin_config.yaml in your home directory:
# ~/vitamin_config.yaml
version: 2026.1
api_integration:
claude_api:
enabled: true
model: claude-3-opus-2026
temperature: 0.2
max_tokens: 2048
citation_style: "Vancouver"
openai_api:
enabled: true
model: gpt-4-turbo-2026
temperature: 0.1
databases:
nih_ods:
use_api: true
cache_expiry_hours: 24
pubmed:
max_sources_per_interaction: 25
year_range: [1990, 2026]
cochrane:
prioritize: true
kfda:
api_endpoint: "https://openapi.kfda.go.kr/v1/2026"
user_profiles:
default:
age: 35
weight_kg: 70
pregnancy_status: false
kidney_function: normal
liver_function: normal
known_allergies: []
current_medications: []
supplements: []For sensitive credentials, use a .env file:
CLAUDE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
KFDA_API_KEY=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
vitamin-analyzer --interaction "Glucosamine + Losartan" --profile defaultvitamin-analyzer \
--supplements "Omega-3 2g, Magnesium glycinate 400mg, CoQ10 200mg" \
--medications "Metformin 500mg, Lisinopril 10mg, Aspirin 81mg" \
--profile elderly-senior-75 \
--output-format markdown \
--include-sources \
--severity-threshold moderatevitamin-analyzer --batch my_supplement_list.csv --output-dir ./reportsCSV format:
supplement,dose,unit,medication,dose,unit
Vitamin_C,1000,mg,Metformin,500,mg
Zinc,15,mg,Amoxicillin,500,mg
| OS | Version | CLI | Plugin Mode | GUI Preview | Status (2026) |
|---|---|---|---|---|---|
| ๐ฉ Windows | 10/11 | โ Full | โ Beta | โ Limited | Active |
| ๐ฆ macOS | 14 (Sonoma)+ | โ Full | โ Full | โ Full | Active |
| ๐ง Linux (Ubuntu) | 22.04+ | โ Full | โ Not planned | Active | |
| ๐ง Linux (Arch) | Latest | โ Full | โ Not planned | Community | |
| ๐ iOS (via Shortcuts) | 18+ | โ N/A | โ Adapted | Experimental | |
| ๐ค Android (Termux) | 14+ | โ Core | โ N/A | โ N/A | Experimental |
| Shell | Status |
|---|---|
| Bash 5.x | โ Full |
| Zsh 5.9+ | โ Full |
| Fish 3.7+ | โ Full |
| PowerShell 7.4+ | โ Full |
| Windows CMD |
This tool implements a dual-LLM arbitration system. For each interaction query:
- Claude performs source summarization and citation extraction
- GPT-4 executes risk scoring and confidence calibration
- Both models vote on interaction severity, with majority rule + tiebreaker logic
vitamin-analyzer --use-dual-engine --consensus-threshold 0.8- Claude API: 5 RPM (requests per minute) default, configurable
- OpenAI API: 10 RPM default with automatic exponential backoff
- KFDA API: 100 requests per day (Korean government limitation)
- All API interactions logged for audit trail compliance
The tool supports 12 languages for query parsing and report generation:
| Language | Query Input | Report Output | Source Citations |
|---|---|---|---|
| ๐บ๐ธ English | โ | โ | โ |
| ๐ฐ๐ท Korean | โ | โ | โ (KFDA) |
| ๐ฏ๐ต Japanese | โ | โ | โ |
| ๐ช๐ธ Spanish | โ | โ | |
| ๐ซ๐ท French | โ | โ | |
| ๐ฉ๐ช German | โ | โ | |
| ๐จ๐ณ Chinese (Simplified) | โ | โ | โ |
| ๐ฎ๐ณ Hindi | โ | ||
| ๐ง๐ท Portuguese (BR) | โ | โ | |
| ๐ท๐บ Russian | โ | โ | โ |
| ๐ธ๐ฆ Arabic | โ | ||
| ๐ฎ๐น Italian | โ | โ |
Language detection is automatic, but can be forced:
vitamin-analyzer --lang ko --interaction "๋นํ๋ฏผ D์ ์นผ์ ์ํธ์์ฉ"The terminal UI adapts to screen width and resolution:
- Wide screens (120+ columns): Full interaction matrix displayed side-by-side with source citations
- Medium screens (80-119 columns): Condensed table with expandable rows
- Narrow screens (40-79 columns): Single-column vertical flow with color-coded severity indicators
- Ultra-narrow (<40 columns): Minimalist output with emoji-only risk indicators (
โ ๏ธ โโ )
| Color | Meaning | Terminal Code |
|---|---|---|
| ๐ด Red bold | Critical interaction | \033[1;31m |
| ๐ก Yellow | Moderate caution | \033[0;33m |
| ๐ข Green | Safe/no interaction | \033[0;32m |
| ๐ต Blue | Information only | \033[0;34m |
| โช Gray | Insufficient data | \033[2;37m |
We provide multi-channel support for all users:
- In-app help command:
/vitamin --help - Documentation site: Full wiki at [docs link placeholder]
- Discord community: Real-time support with response time under 2 hours
| Issue Severity | Response Target | Channel |
|---|---|---|
| ๐จ Critical (false negative interaction) | < 30 minutes | Discord priority |
| < 2 hours | Email + Discord | |
| ๐ถ Medium (configuration issues) | < 8 hours | |
| ๐ท Low (feature requests) | < 48 hours | GitHub Issues |
A 67-year-old patient starts taking Vitamin K2 100 mcg in addition to Warfarin 5mg. The clinician runs:
vitamin-analyzer --interaction "Warfarin + Vitamin K2" --profile anticoagulation-monitoringOutput includes:
- ๐ PubMed citation showing K2 reverses warfarin's effect (INR reduction of 0.5-0.8)
- ๐ฉบ Cochrane review excerpt on dietary vitamin K consistency
- ๐ Dose-response curve (safe K2 intake under 45 mcg/day while on warfarin)
- โฐ Timing recommendation: take K2 12 hours apart from warfarin dose
An athlete asks about Creatine 5g + Caffeine 400mg + Beta-alanine 3.2g:
vitamin-analyzer --interaction "Creatine + Caffeine + Beta-alanine" --profile athlete-male-25Output includes:
- ๐ฌ NIH ODS data showing no negative interaction between creatine and caffeine
- ๐ช Synergy score: 0.82 on a 0-1 scale (moderate beneficial interaction)
- ๐ Timing recommendation: split caffeine and creatine by 2 hours for maximum absorption
This project is licensed under the MIT License - see the LICENSE file for details.
- Claude API usage subject to Anthropic's terms of service (2026)
- OpenAI API usage subject to OpenAI's terms of service (2026)
- KFDA data usage subject to Korean government open data license
- All medical content is derived from public databases; no proprietary clinical data is included
IMPORTANT MEDICAL DISCLAIMER
This tool is designed for informational and educational purposes only. It does not constitute medical advice, clinical diagnosis, or professional healthcare recommendations.
-
No Doctor-Patient Relationship: Use of this software does not establish a physician-patient relationship.
-
Not FDA/KFDA Approved: The AI-generated interactions are not reviewed or approved by any regulatory authority.
-
Limitations of Evidence:
- Some interactions may be based on case reports or animal studies
- Individual responses vary based on genetics, diet, and health status
- Database updates may lag behind latest research (target: quarterly 2026)
-
Always Consult a Professional: Before making any changes to your medication or supplement regimen, consult with a licensed healthcare provider, pharmacist, or registered dietitian.
-
Emergency Situations: If you suspect a serious adverse reaction, contact emergency services immediately (911 in US, 119 in Korea).
-
No Liability: The creators, contributors, and maintainers assume no liability for any harm, injury, or loss resulting from the use of this tool.
We welcome contributions from pharmacologists, dietitians, data scientists, and developers.
- Adding new supplement/drug interaction sources
- Improving citation extraction accuracy
- Expanding the multilingual database
- Building GUI wrappers for non-CLI users
See our CONTRIBUTING.md for detailed guidelines.
The AI-Powered Supplement & Medication Interaction Checker represents a paradigm shift in how we approach polypharmacy safety. Instead of static monographs or siloed databases, this tool offers a living, reasoning interface to the complex ecosystem of modern supplementation.
Whether you're a clinical pharmacist verifying a patient's regimen, a researcher exploring niche interactions, or an individual taking control of your health stack, this tool provides the evidence layer that has been missing from consumer health technology.
Last updated: January 2026 | Version 2026.1.0