health

llm-health

 _ _                 _                _ _   _
| | |_ __ ___       | |__   ___  __ _| | |_| |__
| | | '_ ` _ \ _____| '_ \ / _ \/ _` | | __| '_ \
| | | | | | | |_____| | | |  __/ (_| | | |_| | | |
|_|_|_| |_| |_|     |_| |_|\___|\__,_|_|\__|_| |_|

        Your private, own-risk health concierge.

llm-health is a package-first, local-first health intelligence system for private labs, wearables, records, self-reported context, timelines, reviews, diagnostic gaps, and research queues.

It sits above deterministic health data tools: ingest events, summarize new results, open diagnostic gaps, queue deeper research, compare advice lenses, and preserve provenance. Agent and chat surfaces are interfaces, not the product story.

Initial scope

This scaffold implements the core contracts for:

• event-driven quick reviews after new results;
• smart deep-research job planning;
• diagnostic-gap and test-candidate cards;
• least-harm / conservative-care option cards;
• medication collateral-damage and preventive-protocol review models;
• local JSONL storage suitable for a package-native vault or future llm-wiki adapter;
• a dependency-light CLI that works before the analytics/UI stack is installed.

It intentionally does not diagnose, prescribe, order tests, or auto-change care. It creates reviewable cards, tasks, and research jobs. Use is explicitly at the user's own risk; the CLI gates health-facing HUB commands behind an initial own-risk agreement.

Runtime surfaces

Host	Entry point	Notes
Claude Code	/health, /review, /ingest, /research, /consult	Primary command UX.
OpenAI Codex	@health	Marketplace plugin skill.
OpenCode	instruction file	Use plugins/llm-health-opencode/skills/health/SKILL.md.
Pi / generic agents	instruction file or AGENTS.health.md	Portable fallback when plugins are unavailable.
Terminal/Python	health, llm-health, health-v2	Deterministic CLI and local analytics.

Homebrew install

Public tap install target:

brew tap nvk/tap
brew install llm-health
health agreement show
health config hub-path ~/health --init --accept-risk
health doctor

Use any private local/synced directory for the HUB. Keep raw medical dumps outside Git.

See docs/homebrew.md.

Virtualenv-first development

Use a local virtual environment for all work:

make install-v2
. .venv/bin/activate

For core-only work:

make install

HUB setup

llm-health supports a default HUB/store path in ~/.config/llm-health/config.json.

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

Then commands such as health review --profile rod and health sync-v2 ... use that HUB by default unless --store is supplied.

First-run onboarding

Run health or health welcome for the first-run flow. It starts with the own-risk disclaimer, then asks for an alias-only profile, data dumps to import, and a data-poor questionnaire when the user does not have much history yet. Periodic check-ins use the cheeky-but-useful Dr Visit prompts:

health agreement show
health agreement accept --own-risk
health enroll --alias sol --birth-year 2018 --role child
health data-wishlist
health dr-visit --profile sol --cadence onboarding
health dr-visit --profile sol --cadence monthly --sources
health test-battery --profile sol --scope expanded --sources
health consult --profile sol --specialist auto
health specialists --short  # broad category agents

See docs/onboarding-and-dr-visit.md and docs/test-battery-layer.md.

Quick start

cd llm-health
PYTHONPATH=src python3 -m unittest discover -s tests
PYTHONPATH=src python3 -m llm_health doctor
PYTHONPATH=src python3 -m llm_health init --store .llm-health --accept-risk
PYTHONPATH=src python3 -m llm_health ingest-note --profile rod --marker ALT --value 76 --unit U/L --category liver --flag high
PYTHONPATH=src python3 -m llm_health review --profile rod
PYTHONPATH=src python3 -m llm_health close-gaps --profile rod

If installed as a package:

pip install .
health doctor
health result --profile rod --marker mercury
health review --profile rod

health-assessment-v2 included

The former health-assessment-v2 code is repackaged under llm_health.assessment_v2 and exposed as health-v2. The Homebrew formula installs the package CLI plus v2-core analytics/static-export support; live Panel serving remains an optional llm-health[v2] dev extra. See docs/v2-repackaging.md.

Agent plugins and adapters

First-class agent surfaces are included, modelled after llm-wiki: