Suggested Repair Log!

[w409765910-glitch]

Summary

Windows setup generates statusLine command exceeding Claude Code's ~300ms render cadence — HUD silently fails

Summary

On Windows, the statusLine.command generated by /claude-hud:setup takes 320–390ms per invocation due to PowerShell wrapper overhead. Per CLAUDE.md ("The statusline is invoked every ~300ms by Claude Code"), this means every call is slower than the call interval. Claude Code appears to back off / circuit-break, and the HUD remains completely blank with no error visible to the user.

Calling node.exe directly bypassing the PowerShell wrapper drops invocation time to ~95ms and the HUD renders normally. This suggests the Windows setup template should be revised.

Environment

• OS: Windows 11 Pro 22631
• PowerShell: 5.1 (Windows PowerShell, the default)
• Node.js: v24.15.0 at C:\Program Files\nodejs\node.exe
• Claude Code: 2.1.143
• claude-hud: 0.1.0
• Install path: C:\Users\<user>\.claude\plugins\cache\claude-hud\claude-hud\0.1.0\

Reproduction

1. Install claude-hud on Windows via the marketplace
2. Run /claude-hud:setup
3. Restart Claude Code
4. Observe: status line area above the input box is completely blank

Root cause (timing data)

The setup-generated command:

powershell -NoProfile -NonInteractive -Command "$env:COLUMNS=120; $node=(Get-Command node -ErrorAction SilentlyContinue).Source; ...; $p=(Get-ChildItem ... 'plugins\cache\*\claude-hud\*' ...).FullName; ...; & $node $s"

Measured wall-clock time over 5 runs (stdin = stub session JSON, executed via cmd /c "echo ... | <command>"):

run 1: 340ms
run 2: 390ms
run 3: 372ms
run 4: 354ms
run 5: 320ms

Breakdown:

• PowerShell 5.1 startup: ~150–200ms
• Get-ChildItem + version sort over plugin cache: ~50–100ms
• node.exe cold start: ~100ms
• claude-hud script execution: ~30–50ms

Total: 320–390ms, consistently above the ~300ms cadence documented in your CLAUDE.md.

With a debug Add-Content line added to log every invocation, I observed Claude Code calling the statusLine only at session startup (once or twice), then 6+ minutes of silence despite continuous assistant turns. This matches the symptom of Claude Code disabling/throttling slow status line commands.

Fix that works

Replacing the wrapper with a direct node.exe invocation:

"statusLine": {
  "type": "command",
  "command": "\"C:\\Program Files\\nodejs\\node.exe\" \"C:\\Users\\<user>\\.claude\\plugins\\cache\\claude-hud\\claude-hud\\0.1.0\\dist\\index.js\""
}

New timing:

run 1: 99ms
run 2: 93ms
run 3: 98ms
run 4: 99ms
run 5: 110ms

HUD renders correctly, refreshes continuously, no more silent failures.

Suggested fixes

In priority order:

1. Windows setup should emit a direct node.exe command, not a PowerShell wrapper. Resolve the plugin path and node binary at setup time (when the user is already paying the cost of running /claude-hud:setup) and write the absolute paths into statusLine.command. This is the single highest-impact change — without it the HUD ships broken on Windows.

2. If runtime version auto-discovery is a hard requirement, write a small .cmd batch wrapper to ~/.claude/claude-hud-statusline.cmd that performs the lookup. cmd.exe startup is ~10× faster than powershell.exe. Point statusLine.command at the batch file.

3. Add a /claude-hud:doctor command that:

   • Times the configured command
   • Warns if invocation exceeds ~250ms (safety margin under the 300ms cadence)
   • Detects the "Write-Host wraps node output" anti-pattern (output goes to Host stream, Claude Code reads stdout — produces blank HUD with no error)
   • Verifies the plugin directory resolves with the current glob

4. Make [claude-hud] 正在初始化... (and equivalents) write to stderr, not stdout. When stdin doesn't arrive, the placeholder currently goes to stdout and gets rendered by Claude Code as if it were a real status line. Sending it to stderr would let users see real diagnostic output via Claude Code's debug logs without polluting the status line.

5. Document the Windows-specific 300ms timing constraint in the README, with a one-liner self-test users can paste to verify their setup is fast enough.

Related friction (not bugs in claude-hud, but worth knowing for support)

These tripped me up during diagnosis and may help other Windows users searching for similar symptoms:

• Claude Code's plugin cache has 3 nested levels (plugins\cache\<marketplace>\<plugin>\<version>\). An older glob plugins\cache\*\claude-hud only matches the middle directory and misses the version dir. Current setup uses plugins\cache\*\claude-hud\* which is correct — please keep this in mind if the platform changes structure again.

• statusLine config is read only at Claude Code startup, so users with multiple existing windows won't see changes until each window is restarted. Worth mentioning in setup output ("Restart all Claude Code windows for the new status line to take effect").

• Multiple claude.exe processes are normal (one per window) and not all share state. A debug recipe in the README — "list claude.exe creation times, compare to settings.json mtime" — would short-circuit a lot of confused user reports.

Ask

Could you ship a setup-script fix that defaults to direct node.exe invocation on Windows? Even just hardcoding the resolved version path at setup time (with a note that users should re-run setup after plugin upgrades) would prevent the silent failure mode that currently ships out of the box.

Happy to test a PR against my Windows environment.

---

Thanks for the great plugin — once it's working it's genuinely the best Claude Code status line out there. Hope this debugging session saves you some inbound support time.

Steps to Reproduce

Expected Behavior

Actual Behavior

Environment

• OS:
• Node/Bun version:
• Claude Code version:

Logs or Screenshots