Support env var and ~ expansion in externalUsagePath / externalUsageWritePath

Author: C0DECHEFCreated Sep 10, 2026Updated Sep 10, 2026

Summary

display.externalUsagePath / display.externalUsageWritePath currently require a literal absolute path. Environment variables and ~ are not expanded, and values that fail the absolute-path check are ignored silently — the usage line just disappears with no warning anywhere.

Current behavior (v0.7.1)

  • validateOptionalPath() in src/config.ts only trims the string; no expansion.
  • getUsageFromExternalSnapshot() in src/external-usage.ts rejects any path that fails path.isAbsolute() and returns null — so ${CLAUDE_CONFIG_DIR}/... or ~/... quietly disables the usage line.

Repro: set display.externalUsagePath to ${HOME}/.claude/plugins/claude-hud/glm-usage.json (with the env var actually present in the statusline process) → usage line gone. Absolute path → works.

Motivation

Portable config.json across machines / usernames. Producers of the snapshot (a scheduled job or script) can resolve env vars at runtime, but the HUD config has to hardcode a per-machine absolute path, which defeats dotfile-style sharing of the config.

Proposal

Expand ${VAR} (cross-platform) and optionally ~ and Windows-style %VAR% in these two settings before the absolute-path validation. Happy to open a PR if the approach sounds good.