Episode 2: Installation & Version Guide
Key Takeaway: From zero to HUD display in just three commands β but different platforms have different pitfalls.
2.1 Prerequisites
- Claude Code v1.0.80+
- macOS/Linux: Node.js 18+ or Bun
- Windows: Node.js 18+
2.2 Three-Step Installation
Run these commands inside a Claude Code session:
Step 1: Add marketplace
/plugin marketplace add jarrodwatts/claude-hud
Step 2: Install plugin
/plugin install claude-hud
Step 3: Configure statusline
/claude-hud:setup
Done. HUD appears immediately β no restart needed.
2.3 Linux Notes
On Linux, /tmp is usually a separate tmpfs filesystem. Installation may fail with:
EXDEV: cross-device link not permitted
Fix: Set TMPDIR before launching Claude Code:
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
Then run the installation commands in that session.
2.4 Windows Notes
If setup can't find a JavaScript runtime:
winget install OpenJS.NodeJS.LTS
Restart your shell and re-run /claude-hud:setup.
2.5 Version Guide
claude-hud has three version number sources that can be confusing:
| Source | Version Format | Notes |
|---|---|---|
| Claude Code Plugin Marketplace | 0.1.0 |
Installed via /plugin install claude-hud |
| GitHub Releases | 0.0.1 β 0.0.12 |
Source code releases with incremental features |
| npm Registry | 1.0.0 / 1.1.0 |
npm release, published 2026-03-10 |
This tutorial is based on v0.1.0 (marketplace version). Install via /plugin install claude-hud β simplest method.
v0.1.0 vs npm v1.1.0
| v0.1.0 (Marketplace) | npm v1.1.0 | |
|---|---|---|
| Installation | /plugin install claude-hud |
npm install -g claude-hud |
| Context bar + usage display | β | β |
Config system + /claude-hud:configure |
β | β |
| Multi-line layout (expanded/compact) | β | β |
Chinese labels (language: "zh") |
β | β |
| Tools/Agent/Todo display | β | β |
| Color customization + custom tagline | β | β |
| Cache countdown | β | β |
| Git status | β | β |
| Session token stats | β | β |
The marketplace version is fully featured β no need to install separately from npm.
Feature Milestones
| Version | New Features |
|---|---|
| v0.0.4 | Config system + /claude-hud:configure interactive setup |
| v0.0.6 | Multi-line layout (expanded mode) |
| v0.0.7 | Redesigned default two-line layout + setup wizard |
| v0.0.9 | Usage API reliability + Windows fixes |
| v0.0.10 | Color overrides, custom tagline, session name |
| v0.0.12 | Chinese labels, cost display, session token stats |
Next Episode: Episode 3 breaks down the default two-line layout β what every character on screen means.