Skip to content
HarneryHarnery

harn doctor

harn doctor [--json] [--fix]

Walks through every dep Harnery touches and reports presence + version + install hints.

--fix installs missing managed tools before running the checks. Currently that means ripgrep: a version-pinned, sha256-verified download into Harnery’s own tools directory (~/.local/share/harnery/tools), which harn grep probes directly; see the managed-install section on the grep page.

Severity model

Section titled “Severity model”
  • ✓ ok: present and recent enough
  • ⚠ warn: optional dep missing (the dependent feature degrades; Harnery’s core still works)
  • ✗ fail: required dep missing (Node, git); commands will throw

Exits 0 unless a required dep is missing.

Checks

Section titled “Checks”
Name Required Notes
node required Must be ≥ 20
git required Used by harn file-history, harn context, harn agents, et al
bun optional Daily-driver execution layer; speeds up harn startup
ripgrep optional Fast engine for harn grep (grep fallback works, just slower). --fix installs it; or opt in to auto-install via .harnery/config.jsonc
.harnery/ optional The coord state directory above cwd. Most commands degrade gracefully without it
adapter hooks optional Compares wired agent-hook entries against the current adapter spec. Also reports invalid JSON and, for Codex, strict-schema fields or event names that make Codex reject the whole file (see Keeping hooks current)
workflow:claude-code / workflow:codex / workflow:cursor optional Spawn targets for harn run: is the adapter CLI installed, and how will headless children bill (subscription login vs API key)? A missing CLI warns with the vendor’s official install one-liner + login command; installed-but-unauthenticated warns with the login hint
restic optional Required for harn backup
rclone optional Required for harn sync
playwright optional Required for harn browse (module + browsers installed)
python3 optional Some examples shell out to Python

Examples

Section titled “Examples”

Human-readable report (default):

Terminal window
$ harn doctor
✓ node        24.3.0
✓ git         2.34.1
✓ bun         1.3.3
✓ .harnery/   /home/you/projects/myrepo/.harnery
⚠ restic      missing (needed for `harn backup`)
    ↳ apt-get install -y restic
⚠ rclone      missing (needed for `harn sync`)
    ↳ curl https://rclone.org/install.sh | sudo bash
✓ playwright  module + browsers at /home/you/.cache/ms-playwright
✓ python3     Python 3.10.12


6 ok, 2 warn, 0 fail

JSON for scripts / CI / dashboards:

Terminal window
$ harn doctor --json
{
  "checks": [
    { "name": "node",       "severity": "ok",   "detail": "24.3.0" },
    { "name": "git",        "severity": "ok",   "detail": "2.34.1" },
    ...
  ],
  "summary": { "total": 9, "ok": 7, "warn": 2, "fail": 0 }
}

Keeping hooks current after an upgrade

Section titled “Keeping hooks current after an upgrade”

Updating Harnery (npm i -g harnery@latest, npm update harnery, or git pull for a cloned checkout) is enough for code fixes: your wired hooks call the agent-hook binary, so they immediately run the new code. No re-init needed.

The one exception is when a release adds, renames, or retires a hook event. Re-run harn init to migrate the Harnery-owned entries without touching third-party hooks. harn doctor’s adapter hooks check catches this, and a one-line nudge also appears at the start of your next session:

Terminal window
$ harn doctor
...
⚠ adapter hooks  .claude/settings.json: 2 missing (sub-agent-start, post-tool-use-failure)
    ↳ run `harn init` to wire the new hook(s) (idempotent)

The check only performs missing-hook drift checks for a adapter the project has already opted into (at least one Harnery hook is wired), so a bare .claude/settings.json never triggers a false warning. Invalid JSON is always reported. Codex’s parser is strict, so doctor also flags unsupported top-level fields and event names before they can silently disable every hook. Re-run harn init to remove legacy Harnery-owned events after repairing any invalid third-party configuration.