/doctor on Windows: reports valid JSON as FAIL (jq missing) and can't find config when CLAUDE_CONFIG_DIR is set

Status Open
Reported on v2.1.215
Maintainer reply None cached
Activity 0 comments · opened Jul 20, 2026

Environment: Windows 11, Claude Code 2.1.215, npm global install, Git Bash available, CLAUDE_CONFIG_DIR set to a non-default location.

Issue 1 — /doctor reports valid settings files as FAIL when jq is absent.

Every config read in the /doctor flow invoked jq (e.g. jq '.permissions.defaultMode', jq empty <file> for parse checks). jq does not ship with Windows, Git Bash, or Claude Code, so each parse check errored — and the error was rendered as FAIL against each file. The files were valid JSON throughout.

This is worse than failing loudly: a healthy config is reported as corrupt, which would send a user chasing a settings problem that doesn't exist.

=== settings parse checks ===
/usr/bin/bash: line 1: jq: command not found
FAIL C:/Users/<user>/Box/.claude/settings.json
FAIL C:/Users/<user>/Box/.claude/settings.local.json
FAIL C:/Users/<user>/Box/.mcp.json

Issue 2 — /doctor reads ~/.claude.json and ~/.claude/settings.json even when CLAUDE_CONFIG_DIR points elsewhere.

With CLAUDE_CONFIG_DIR set, the real files live at $CLAUDE_CONFIG_DIR/.claude.json and $CLAUDE_CONFIG_DIR/settings.json, but the home-relative paths were read instead.

Result: FileNotFoundError on the config file, so usage counters, plugin/skill inventory, permission mode, and hooks config were all unreadable. Since CLAUDE_CONFIG_DIR is a documented, supported setting, /doctor can't complete for anyone who uses it. The same applies to the transcript scan (~/.claude/projects/).

Expected:

  • Resolve config through CLAUDE_CONFIG_DIR when it is set, falling back to ~/.claude only when it isn't.
  • Parse JSON without requiring an external binary — or detect that jq is unavailable and fall back (Node is guaranteed present) rather than reporting valid files as FAIL.

Workaround: reimplemented the checks in Python, reading os.environ['CLAUDE_CONFIG_DIR']. All checks then passed — the setup was healthy the whole time.

Repro:

  1. On Windows without jq on PATH, set CLAUDE_CONFIG_DIR to a non-default directory.
  2. Run /doctor.
  3. Observe: settings files reported FAIL, and config-dependent checks (usage counters, plugins, permission mode, hooks) unavailable.

View original on GitHub ↗