A fast, beautiful terminal usage visualizer for Claude Code sessions.

Inspired by jarrodwatts/claude-hud, rewritten from scratch in Rust for speed and minimal footprint.

[Claude Sonnet 4] │  h0z06mx/usage-viz  main* │  33h 31m │  $2.47 │ +580 -38
Context ███████▌░░░░ 63% (126.0k / 200.0k)
Usage  ████▌░░░░░ 45% (5h) │ resets in 3h 0m │ █▎░░░░░░░░ 12% (7d)
Cost    $2.47 │ API: 128.0s
 Tools  Bash: source "$HOME/.cargo/env"... │  Bash x8 │  Edit x6 │  Read
 Tasks  ██████  All complete (6/6)

Claude Code's statusline API runs every 300ms. The original Node.js HUD has ~200ms cold start and ~40MB runtime. That's too heavy for a status bar.

• Context window — smooth progress bar with color thresholds (green → yellow → red)
• Rate limits — 5-hour and 7-day windows with reset countdown
• Cost tracking — session cost with API duration
• Tool activity — running tools with spinner, completed grouped with counts, errors highlighted
• Agent status — sub-agent entries with elapsed time
• Task progress — mini progress bar with current task and completion count
• Git integration — branch, dirty state, ahead/behind
• Session duration — parsed from transcript timestamps

• Catppuccin Mocha 24-bit truecolor palette
• Nerd Font icons (degrades gracefully without them)
• 8-level smooth progress bars (▏▎▍▌▋▊▉█) for sub-character precision
• Adaptive bar width based on terminal size

# Clone and build
git clone https://github.com/patchmyday/usage-viz.git
cd usage-viz
cargo build --release

# Binary at target/release/usage-viz (476KB)

• Rust 1.70+ (for building)
• A terminal with truecolor support (iTerm2, WezTerm, Kitty, Alacritty, etc.)
• Optional: Nerd Font for icons

usage-viz reads JSON from stdin, the same format Claude Code pipes to statusline plugins:

# Test with mock data
echo '{"model":{"display_name":"Claude Sonnet 4"},"cwd":"/path/to/project","context_window":{"context_window_size":200000,"used_percentage":63.1},"cost":{"total_cost_usd":1.87,"total_api_duration_ms":98200,"total_lines_added":580,"total_lines_removed":12}}' | ./target/release/usage-viz

Copy the binary somewhere on your PATH and configure Claude Code to use it:

cp target/release/usage-viz ~/.local/bin/

# In your Claude Code settings, add as a statusline command:
# "statusline": "usage-viz"

src/
  main.rs              Entry point: stdin -> parse -> git -> render
  types.rs             All shared types (StdinData, TranscriptData, etc.)
  stdin.rs             JSON parsing, model normalization, rate limits
  git.rs               Git branch/status via shell commands
  transcript.rs        JSONL parser with SHA-256 file cache
  render/
    mod.rs             Orchestrator: assembles lines, ANSI truncation
    colors.rs          Catppuccin Mocha palette, smooth_bar(), sparkline()
    icons.rs           Nerd Font icon constants
    lines/
      project.rs       Model, path, git, duration, cost, lines changed
      context.rs       Context window usage bar
      usage.rs         Rate limit bars with reset countdown
      cost.rs          Session cost + API duration
      tools.rs         Running/completed tool activity
      agents.rs        Sub-agent status with elapsed time
      todos.rs         Task progress bar

• No async runtime — the tool reads stdin, renders, exits. No event loop needed.
• No ratatui — this is "print and exit", not an interactive TUI. Raw ANSI is lighter.
• No chrono — hand-rolled ISO 8601 parser saves ~200KB vs pulling in chrono.
• SHA-256 transcript cache — avoids re-parsing large JSONL files every 300ms cycle.

[profile.release]
opt-level = "z"       # Optimize for size
lto = true            # Link-time optimization
codegen-units = 1     # Single codegen unit
strip = true          # Strip symbols
panic = "abort"       # No unwinding

MIT