Doctor
werbos doctor — green/red checklist of the local environment. Run after install or whenever werbos chat starts misbehaving.
werbos doctor runs a handful of concurrent checks against the local
environment and prints a green/red checklist. It’s the answer to “why
does werbos chat keep timing out / why won’t the model load / which
sibling SHA is wrong this time.”
werbos doctor
Exit code is 1 on any FAIL, so shell glue can branch on it.
What it checks
| Check | What’s verified |
|---|---|
| ollama | Daemon reachable on --host (default http://localhost:11434)? |
| models | Are the expected model tags pulled? Default is llama3.1:8b. |
| sibling-shas | Local HEAD of each sibling repo (pitts, pfm, mcculloch, partyparrot) matches the SHA pinned in pyproject [siblings]? Walks ../ and matches by remote.origin.url, so name mismatches like P.F.M. ↔ pfm/ resolve cleanly. |
| venv-editable | Which siblings (and werbos itself) are editable installs? Warns if pip list is unavailable. |
| tailscale | Backend Running per tailscale status --json? Warn-soft if the binary is missing. |
Each check returns OK / WARN / FAIL with a one-line detail. Use
--no-color for piping or non-TTY output. Pass --host to check a
non-default Ollama daemon. Pass --models tag1,tag2 to check
additional model tags beyond the default.
When to run
- After install. Confirms the venv, siblings, and Ollama daemon are all wired up before you start a chat session.
- After
git pullon werbos. Sibling-SHA pins drift; doctor surfaces the mismatch in seconds rather than a 500 mid-chat. - After a model rebuild. Catches the
ollama pull <tag>you meant to run last week. - In CI. Exit-1 on FAIL means
werbos doctor || exit 1is a valid pre-flight check.
Stdlib only
The implementation is urllib + subprocess + tomllib — no extra
dependencies. Adding a new check means appending one function and
one row to the renderer.