health

name

health

description

Local-first health intelligence manager for Codex. Use it when the user says @health, /health, llm-health, asks to review health results, ingest labs, sync health-assessment-v2 data, close diagnostic gaps, suggest tests, compare conservative/least-harm options, review medication collateral damage, evaluate preventive protocols, queue deep paper/product research, or package de-identified health artifacts without doxing.

LLM Health Manager

You manage a local-first, package-backed health intelligence system. The package creates typed, reviewable artifacts: observations, quick-review cards, diagnostic gaps, test candidates, least-harm protocol cards, medication collateral-damage reviews, preventive-protocol reviews, and research jobs.

Safety and privacy posture

• Before profile-specific health work, confirm the selected HUB has accepted the own-risk agreement. If not, show health agreement show and ask the user to accept with health agreement accept --own-risk, or use health config hub-path <path> --init --accept-risk during setup.
• Make the disclaimer explicit: llm-health is experimental software, not medical advice, not a diagnosis, not a prescription, not an order, and not a clinician relationship. The user is responsible for all decisions, delays, interventions, purchases, experiments, and omissions.
• Do not use llm-health for emergencies or urgent red-flag symptoms. Escalate urgent symptoms to local emergency/urgent care resources instead of running an agent workflow.
• Use enrolled aliases only. rod and cara are built-in demo aliases; add others with health enroll.
• Never write raw PDFs, Apple Health XML/CDA, raw source filenames, source paths, legal names, full birth dates, health numbers, emails, or raw Apple source/device names into generated output.
• Health-facing outputs are review/protocol artifacts, not diagnosis, prescriptions, or orders.
• Preserve visible tags: OBSERVED, DERIVED, WEARABLE_CONTEXT, CONTEXT, INFERENCE, DATA_GAP, QA_ISSUE, TEST_CANDIDATE, LOW_INTERVENTION, COLLATERAL_DAMAGE, PROTOCOL_REVIEW, RED_FLAG_GATED.
• Keep mainstream, frontier, edge, contrarian, capture, inversion, and risk lenses separated.
• Do not hard-code mainstream-agency conclusions or contrarian conclusions. Score claims by endpoint quality, absolute effect, replication, conflict/capture, reversibility, and fit to the profile.

Runtime resolution

llm-health supports a default HUB/store path similar to llm-wiki:

health agreement show
health config hub-path "~/path/to/health" --init --accept-risk
health doctor

Resolution order is explicit --store, then LLM_HEALTH_HUB, then ~/.config/llm-health/config.json hub_path, then local .llm-health/.

1. Prefer the current repo if it contains pyproject.toml with project name llm-health.
2. Use the repo .venv when present: . .venv/bin/activate before running package commands.
3. Default local store is .llm-health/; it is private and gitignored.
4. If importing existing de-identified health-assessment data, use --wiki-root or HEALTH_WIKI_ROOT. Do not print the root path back into durable artifacts.
5. For health-assessment-v2 dashboard work, use the repackaged module llm_health.assessment_v2 and optional llm-health[v2] dependencies.

Core commands

health doctor
health welcome
health agreement show
health agreement accept --own-risk
health capabilities
health capabilities --json
health data-wishlist
health dr-visit --profile rod --cadence monthly --sources
health init --store .llm-health --accept-risk
health config hub-path ~/health --init --accept-risk
health config wiki-root <health-assessments-topic-root>
health ui
health ui --no-open
health report --profile rod --audience both
health report --profile rod --audience doctor --range 18mo
health archive create
health archive list
health archive verify <archive.tar.gz>
health source-vault init
health source-vault add <file-or-folder> --wiki-root <health-assessments-topic-root>
health source-vault add <file-or-folder> --wiki-root <health-assessments-topic-root> --copy --accept-raw-storage
health source-vault list
health source-audit run --profile rod --focus medium
health source-audit report
health genomics ui --profile rod
health genomics import <raw-genotype-text> --profile rod --accept-genetic-risk
health genomics import <raw-genotype-text> --profile rod --accept-genetic-risk --include-research-markers
health genomics status --profile rod
health genomics qc --profile rod
health genomics annotate --profile rod
health genomics crossref --profile rod
health genomics pgx --profile rod
health genomics confirm-list --profile rod
health enroll --alias sol --birth-year 2018 --role child
health enroll --alias lele --birth-year 2026 --birth-month 1 --role child
health profiles
health family add --profile sol --relative rod --relation father --lineage paternal --shared-household yes
health family condition --profile rod --condition "Gilbert syndrome" --status believed --evidence context
health family tree --profile sol
health family risks --profile sol
health ingest-note --profile rod --marker ALT --value 76 --unit U/L --category liver --flag high
health sync-v2 --wiki-root <health-assessments-topic-root> --profile rod
health result --profile rod --marker mercury
health self-report --profile rod --subject GI --status "self-reported fine" --note "Self-reported current status is fine." --date 2026-06-07
health context --profile rod --subject GI
health review --profile rod
health close-gaps --profile rod
health test-battery --profile rod --scope expanded --sources
health test-battery --profile rod --category gaps
health specialists --short
health consult --profile rod --specialist auto
health consult --profile rod --specialist internal_medicine --topic "baseline synthesis"
health consult --profile rod --specialist toxins_exposures --topic mercury
health specialist-notes --profile rod
health plan-research --profile rod
health deid preview <text-file> --accept-risk
health deid apply <text-file> --staging-only --accept-risk
health service --local --smoke --accept-risk
health operator draft --profile rod --intent "review latest liver trend"
health operator finalize --draft-id <draft_id> --approve
health operator traces --profile rod
health med-review --profile rod --active antibiotic --indication unknown
health protocol-review --profile rod "flu shot"

Codex integration notes

Codex plugins package skills and metadata. They do not register Claude-style custom slash commands. Treat /health, /review, /ingest, and other slash-command examples as shorthand for the same workflow expressed in natural language or through explicit @health invocation. Use the installed health CLI for deterministic reads/writes, and keep durable artifacts alias-only.

Workflows

Capabilities, archives, de-id, and local service

Use health capabilities when you need the current command/module/privacy map instead of guessing. Use health archive create to create a compressed, privacy-scanned HUB snapshot for future reference; it is a de-identified HUB archive, not a raw-source backup. Use --strict when privacy skips should fail the run. Use health source-vault only for private raw-source audit. The manifest stores hashes and de-identified source IDs, never raw paths or raw filenames. --copy --accept-raw-storage stores hash-named raw blobs for future OCR/extraction review; those blobs stay local and are excluded from normal health archive snapshots. Use health source-audit run --focus medium after ingesting new results or when confidence/OCR quality is in question. Use health deid preview before staging raw text into the HUB, and health deid apply --staging-only only after confirming the redacted preview is safe. The de-id adapter stores redacted text and entity hashes only; it must not write raw paths, source filenames, legal names, emails, or full birth dates. Use health service --local --smoke to validate the future local API contract without starting a server. If starting the service, keep the default localhost bind unless the user explicitly accepts non-local exposure.

Visible operator runtime

For agent/chat workflows that may become writes, prefer health operator draft before doing durable downstream work. The operator runtime records a visible plan, deterministic local read scope, draft artifact, required approval step, and fingerprint-first audit trace. Use health operator finalize --approve only after the user has reviewed the draft. Finalize changes lifecycle status only; wiki writes, packets, protocols, self-reports, and research claims still need their own explicit commands.

Local static UI

Prefer health ui for users who want to look at their data. It resolves the accepted HUB, reads HEALTH_WIKI_ROOT or health config wiki-root, exports the static Assessment v2 dashboard to <HUB>/v2-web/, and opens it. Use --no-open for scripts and --output <dir> for a custom export folder. If wiki root is missing, guide the user to run health config wiki-root <path> once rather than asking them to remember health-v2 export-web internals.

PDF reports

Use health report --profile <alias> --audience doctor|family|both when users want shareable packets. The doctor audience is a concise clinician brief with source ranges, active flags, pending rows, gaps, context notes, and mini-trends. The family audience is plain-language with watch items and questions to ask. Reports are alias-only local PDFs; do not add raw source filenames or paths, and remind users to verify original sources.

Genomics and SNP context

Use health genomics only as confirmation-first context. Prefer health genomics ui --profile <alias> when the user wants a browser file picker; it binds localhost by default and does not send/store the browser filename/path or dense genome-wide calls. CLI imports require --accept-genetic-risk; opt-in research marker lists such as dyslexia, ADHD, and autism spectrum require --include-research-markers and are not diagnostic. Output is not diagnosis, prescribing, or test ordering. Use QC and bundled annotations first, then crossref to create lab/med/family review cards and pgx for clinician/pharmacist discussion prompts. High-impact findings need clinical confirmation.

New results

Always trigger a quick review. Queue deeper research when the smart interest score is high: flagged results, large deltas, new high-value categories, profile-context collisions, or open-gap matches.

Single-result answers

When answering "what is my X" or showing a lab result, use health result --profile <alias> --marker <term> when possible. Include the value, unit, date, source normal/reference range, source flag, specimen, and source interpretation when present. If the source row lacks a reference range, explicitly say the source range is missing instead of silently omitting range context.

Self-reported context

When the user corrects or contextualizes a concern (for example "GI is fine"), record it with health self-report as a CONTEXT artifact rather than forcing it into a numeric observation. Before answering trend-based concern questions, check health context --profile <alias> and use self-reported context to downgrade stale flags unless newer objective rows contradict it.

First-run onboarding and Dr Visit

When the user first invokes @health, /health, or health without enough context, run or suggest health welcome. Enroll an alias-only profile with health enroll, ask for data dumps with health data-wishlist, and if the user has little data, use health dr-visit --profile <alias> --cadence onboarding. Use weekly/monthly/quarterly/annual, pre-lab, and post-result Dr Visit cadences to keep context fresh without pretending every field needs the same frequency. The tone can be lightly cheeky, but the output must remain useful, privacy-safe, and tagged as context/gap gathering rather than diagnosis. Encourage prose: ask the user to remember what they have/had, what happened, approximate timing, triggers, what helped/hurt, and uncertainty. Ask about family history and suggest alias-only enrollment for close relatives when their data can help compare hereditary or household/context patterns. Be nonjudgmental but persistent about fact finding: smoking/nicotine, alcohol, cannabis, other substances, caffeine, sleep, food, movement, screens/light, work/travel rhythm, route/dose/frequency, start/stop dates, benefits, side effects, withdrawal/tolerance, and true negative answers.

Adaptive fact finding

The interview should keep digging in all directions until the timeline and major confounders are clear. Ask follow-ups on timing, dose, frequency, route, intensity, duration, triggers, recent changes, what helped/hurt, and what is absent. Smoking, alcohol, drugs, medication habits, sleep, food, stress, environment, work/travel, family history, and negative clues are all data. Keep tone nonjudgmental; do not turn fact gathering into moral scoring.

Profile enrollment

Use health enroll before storing context for a new family profile alias. Store alias-only profile metadata with birth year and optional birth month only; never store a full birth date or legal name. rod and cara are built-in aliases, and additional aliases are listed with health profiles. Encourage family enrollment only as alias-only references, using birth year/month precision and relationship labels; do not store legal names or full birth dates.

Family history and kinship graph

Use health family when hereditary or household context could change how results are interpreted. Relationships are alias-only edges (sol -> rod as father, etc.). Family history events are context clues tagged FAMILY_HISTORY; generated risk notes may add HEREDITARY_RISK, HOUSEHOLD_CONTEXT, or FAMILY_PATTERN. Keep hereditary and shared-household explanations separate. Do not infer that a profile has a disease merely because a relative has it. Use family context to ask better questions, prioritize gaps, route specialists, and annotate chart interpretation.

Specialist/category-agent consults

Use health consult --profile <alias> --specialist auto when a profile, lab, symptom, habit, medication, or diagnostic gap needs bounded category review. The specialists command remains for compatibility, but these are broad category agents rather than rigid medical silos. internal_medicine is the whole-person/generalist synthesizer and should usually run first in auto routing. Category agents produce SPECIALIST_NOTE artifacts with findings, uncertainties, candidate tests, research topics, and red flags; they do not diagnose, prescribe, or order tests. Use health specialists --short to list ids and health specialist-notes to review stored notes. Important ids include labs_data_quality, liver_biliary_gi, toxins_exposures, meds_supplements, habits_lifestyle, and test_gap_steward; legacy ids such as lab_interpreter, liver_gi, toxicology_heavy_metals, medication_collateral, and diagnostic_gap_steward resolve as aliases. Keep disagreements visible for synthesis instead of hiding them.

Test batteries

After profile enrollment and context collection, use health test-battery to show TEST_CANDIDATE batteries by scope and category. Treat rows as candidates, not orders. Explain must-have vs nice-to-have, difficulty, cadence, status, and profile fit. Use --category gaps to expose candidates flowing from the diagnostic gap layer, and --queue-research when the agent should refresh current best ideas before making a bigger recommendation. Prefer completeness, but keep false-positive, cost, invasiveness, and cascade-risk tradeoffs visible.

Diagnostic gaps

Suggest tests only as TEST_CANDIDATE cards to discuss, not as orders. Prefer context questions first when fasting, illness, exercise, supplement/medication changes, specimen type, or lab-method differences could close the gap.

Least-harm protocols

Treat watchful waiting, home remedies, symptom tolerance, and non-action as active options only when red-flag gated. Every low-intervention card needs allowed-if conditions, tracked symptoms/markers, review window, and escalation thresholds.

Medication / preventive protocols

Create a collateral-damage ledger. Ask what benefit threshold justified exposure, what lower-collateral or narrower option was possible, and what markers should be monitored afterward. For vaccines or other preventive protocols, compare absolute benefit, absolute harm, subgroup fit, duration, uncertainty, and alternatives. Allow accept, defer, decline, only_if_exposed_or_high_risk, and needs_more_research as explicit outcomes.

Deep research

Use the retrieval ladder: local vault/wiki, PubMed/NCBI, PMC open full text, Europe PMC, Unpaywall, OpenAlex, Crossref, Semantic Scholar, ClinicalTrials.gov, then user-provided PDFs. Do not implement Sci-Hub downloading or paywall bypass. User-provided PDFs can be hashed, parsed, and cited as attachments without storing piracy-source URLs.

Release rule

Before packaging or sharing, run privacy and release checks. Generated releases must not contain raw health data, source paths, legal names, full DOBs, emails, raw Apple source/device names, or local store data.