llm-health install guide

1. read this first

llm-health is built for people who want a private health memory that survives chat sessions. the durable record is a local hub: alias-only profiles, observations, self-reported context, quick reviews, diagnostic gaps, test candidates, specialist/category notes, and research queues.

the chat surface is intentionally fuzzy. you can type @health whats my mercury?, @health add today's weight 92.7kg, or @health plot liver with weight overlay. the agent should route that to deterministic local tools, then leave a reviewable artifact when it writes anything.

the hard line: this is not a doctor. use it as a personal research and organization layer, not as permission to delay care, change medications, skip urgent evaluation, or treat a model answer as truth.

2. install with homebrew

the public install path is the nvk homebrew tap. this installs the core health / llm-health CLI and the packaged health-v2 core commands.

brew tap nvk/tap
brew install llm-health
health --version
health doctor

you should see llm-health 0.0.1 or newer, and health doctor should print the resolved config and hub state. if you installed an older formula, update the tap first:

brew update
brew upgrade llm-health

3. initialize a private hub

the hub is the local health store. it should be private, backed up if you care about it, and kept out of git. the shortest setup uses ~/health:

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

if you want the hub in iCloud Drive so multiple Macs can see it, quote the path because it contains spaces:

health config hub-path "$HOME/Library/Mobile Documents/com~apple~CloudDocs/health" \
  --init --accept-risk

the config file lives at ~/.config/llm-health/config.json. command resolution order is explicit --store, then LLM_HEALTH_HUB, then that config file, then a local .llm-health/ fallback.

4. first-run onboarding

start with aliases, not legal names. then ask the system what data dumps would help and run a data-poor interview if you do not have much history yet.

health enroll --alias alex --birth-year 1983 --role adult
health data-wishlist
health dr-visit --profile alex --cadence onboarding
health test-battery --profile alex --scope expanded --sources
health consult --profile alex --specialist auto

good initial data dumps include labs, clinical portal exports, medication/supplement lists, Apple Health exports, wearable summaries, symptom timelines, family history, and prose notes about what you remember. prose matters because many useful facts never appear in a lab table.

5. fuzzy input examples

after the CLI is installed and your agent surface can see it, use natural language. the agent should infer aliases, dates, markers, categories, and intent when safe; it should ask before risky writes.

@health whats my mercury?
@health what is rods latest mercury and expected range?
@health why is liver flagged?
@health show liver category for rod, all time
@health overlay weight on ALT and AST for the last 18 months
@health add today's weight of 92.7kg
@health GI is fine, update as self reported
@health record 400mg albendazole single dose two weeks ago
@health close gaps for cara
@health what tests would reduce uncertainty the most?
@health queue deeper research on bilirubin and Gilbert syndrome
@health export the plotted charts as a PDF

the equivalent explicit commands still exist for repeatable scripts:

health result --profile alex --marker mercury
health review --profile alex
health close-gaps --profile alex
health test-battery --profile alex --scope expanded --sources
health consult --profile alex --specialist auto

6. agent surfaces

the package ships templates for Claude Code, Codex, OpenCode/Pi, and generic AGENTS.health.md use. the CLI is still the deterministic core; the agent is the fuzzy router and review writer.

find packaged templates

health plugin-paths
health plugin-paths --kind claude
health plugin-paths --kind codex
health plugin-paths --kind opencode
health plugin-paths --kind agents

Claude Code

Claude Code is the primary slash-command UX. when the public marketplace entry is available, the intended command is:

claude plugin install health@llm-health

until then, use the packaged path from health plugin-paths --kind claude as the local plugin source for your Claude install.

OpenAI Codex

Codex gets the @health skill through a native plugin mirror. when using the marketplace path:

codex plugin marketplace add nvk/llm-health
# open /plugins, enable LLM Health, then use @health

for local testing, use the path printed by health plugin-paths --kind codex.

OpenCode and Pi

point your instruction file setting at the packaged skill path, or use the raw repo path if you are tracking source directly:

{
  "instructions": [
    "https://raw.githubusercontent.com/nvk/llm-health/master/plugins/llm-health-opencode/skills/health/SKILL.md"
  ],
  "permission": {
    "external_directory": {
      "~/health/**": "allow",
      "~/.config/llm-health/**": "allow"
    }
  }
}

7. health-v2 dashboard

health-v2 is the analytics/dashboard stack repackaged from the earlier health-assessment-v2 work. the Homebrew formula installs the core/static-export path by default.

health-v2 doctor
health-v2 --help

use it for timelines, categories, normal bands, overlays, chart exports, wearable context, and local analytics. the live Panel server remains a Python/dev extra; the Homebrew package focuses on CLI and static-export support.

8. sync an existing health wiki

if you already have a de-identified health-assessments llm-wiki topic, sync it into the package hub and run profile reviews:

export HEALTH_WIKI_ROOT="$HOME/Library/Mobile Documents/com~apple~CloudDocs/wiki/topics/health-assessments"
health sync-v2 --wiki-root "$HEALTH_WIKI_ROOT" --profile all
health review --profile rod
health close-gaps --profile rod

keep raw PDFs, clinical dumps, Apple Health exports, full names, source paths, and full dates of birth out of public repositories and public chats. sync de-identified rows and artifacts only.

9. privacy checklist

• use aliases for people and avoid legal names in artifacts.
• store raw medical files outside git; commit only de-identified examples.
• do not publish source file paths, full dates of birth, Apple device/source names, or portal identifiers.
• grant iCloud/Dropbox/filesystem access only to the launcher app that actually runs the agent.
• run health doctor after changing hub paths, installing plugins, or moving machines.
• assume the agent can be wrong. prefer raw values, dates, ranges, source notes, and visible uncertainty.

10. troubleshooting