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

• ✓ 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

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
git hooks	optional	Reports whether the project has Harnery’s managed git-hook regions (ADR 0068) and whether they are current. A project that never ran init gets a warn naming what is missing (commit guard, claim pruning) with the init remedy; never an error, and init --check stays green for it
adapter hooks	optional	Compares wired agent-hook entries against the current adapter spec. Also flags an adapter whose CLI is installed but which has no Harnery hooks at all, reports invalid JSON, and, for Codex, strict-schema fields or event names that make Codex reject the whole file (see Keeping hooks current)
codex:hook authorization	optional	Uses Codex app-server’s read-only hooks/list method to distinguish trusted and enabled Harnery commands from new, modified, disabled, or unverifiable hooks. It never grants trust
codex:WSL bridge	optional	In a Windows-native Codex task running inside WSL, verifies that CODEX_THREAD_ID arrived and that WSLENV will forward it to later WSL processes. It also warns when Codex mid-flight onboarding was recorded during the last 48 hours, even if the current bridge is healthy
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

Human-readable report (default):

$ 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:

$ 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

After updating Harnery (npm i -g harnery@latest, npm update harnery, or git pull for a cloned checkout), re-run harn init. Existing commands pick up the new code immediately. Init migrates Harnery-owned entries without touching third-party hooks, and it replaces the V3 epoch only when the schema or adapter capability contract changed. A build-only update keeps the current epoch and its live sessions. harn doctor and harn init --check catch the drift:

$ 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 reports drift only for an 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. It catches missing, stale, duplicated, misplaced, and retired Harnery entries. 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 after repairing any invalid third-party configuration.

An adapter that was never wired at all

Drift checks compare a wired adapter against the spec, so on their own they say nothing about an adapter with no Harnery hooks — including one whose settings file does not exist. That silence is deliberate (see above), but it hides a real failure: if that adapter’s CLI is installed, an agent can start a session through it and register nothing at all, while doctor still reports every other check green.

So doctor warns when both are true: the project plainly uses Harnery hooks (some other adapter is wired), and the unwired adapter’s CLI is installed.

$ harn doctor
...
⚠ adapter hooks  .codex/hooks.json: codex CLI installed, no harnery hooks wired
    ↳ run `harn init --adapter codex` (idempotent, additive)

Both conditions are load-bearing. A project that has never run harn init stays quiet, and so does one that simply doesn’t have Codex installed — that case is already covered by the workflow:codex check. Wiring the adapter clears the warning; there is no separate opt-out, so a project that has an adapter CLI installed and deliberately wants it unwired will keep seeing it.

Codex hook authorization

The adapter hooks check answers whether .codex/hooks.json is valid and current. It cannot answer whether Codex will run those commands. Codex keeps a separate path-and-hash authorization record for every unmanaged hook.

On a native host, doctor asks the active Codex CLI for hooks/list through its app-server protocol. The result is read-only:

• trusted and managed, when enabled, report ok;
• untrusted and modified report warn with the review instructions;
• disabled hooks report warn;
• a missing, incompatible, or unreachable app server reports authorization as unverified rather than green.

⚠ codex:hook authorization  9 of 9 Harnery hooks require review (9 new, 0 modified)
    ↳ terminal UI: run `/hooks`; Codex Desktop: open Settings > Hooks; after approval, start a fresh task

The check filters the response to Harnery’s agent-hook commands. It does not read Codex’s private configuration format, persist the returned hashes, call a trust-write method, or run a hook to test it.

Windows-native Codex with a WSL project

When Codex runs on Windows while the project and Harnery run in WSL, the task identity has to cross that process boundary. harn doctor checks both parts of the contract: the current process must have CODEX_THREAD_ID, and WSLENV must include that variable so later WSL commands keep the same identity.

The same check runs during Codex SessionStart when the adapter reports a \\wsl.localhost or \\wsl$ workspace. That UNC path distinguishes the Windows-to-WSL bridge from Codex running natively inside WSL. Healthy sessions print nothing. If the bridge is incomplete, the agent sees a warning before it starts work and can run harn doctor for the specific failure.

The live check is only one part of the result. doctor also reads recent, privacy-safe mid_flight_onboarding diagnostics. This catches intermittent identity drops that have already cleared. The diagnostics record forwarded environment variable names, never their values.

Harnery does not add Git safe-directory entries or approve Codex hooks. Those are machine-level trust decisions. The diagnostic reports bridge drift but leaves authorization with Git and Codex.

The Linux Codex binary inside WSL may have a different version, configuration home, and trust store from the Windows process that owns the Desktop task. harn doctor therefore reports hook authorization as unverified in this hybrid mode instead of querying the wrong runtime. A Windows host bridge can call the same hooks/list method on the Windows-native Codex runtime with the project’s UNC path. Review any warning in Codex Desktop and start a fresh task after approval.