convez.ai
Plugin
Fyko

claudehud

Fyko/claudehud

Ver no GitHub
BomPluginScore · de 0 a 100

a feature-rich claude code statusline written in rust

Instalação

$npx convez-ai Fyko/claudehud

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
7
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 1 semana
Versão
v0.1.0-alpha.11
Issues abertas
10
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

claudehud

example.png

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/fyko/claudehud/main/install.sh | sh
# Windows
irm https://raw.githubusercontent.com/fyko/claudehud/main/install.ps1 | iex

A Rust rewrite of my personal Claude Code statusline bash script. Renders in ~2.6ms instead of ~437ms by replacing bash interpreter startup + multiple jq/git subprocess calls with a compiled binary and an mmap-backed git status daemon.

Inspired by kamranahmedse/claude-statusline.

Status incidents

When status.claude.com reports an active incident (or in-progress scheduled maintenance), claudehud emits a hyperlinked line directly below line 1:

Elevated API errors · started 12m ago    +1 more

The daemon polls https://status.claude.com/history.atom every 5 minutes using a conditional GET, so most hits return 304 Not Modified. When an incident is active, the most-recently-updated entry is shown; the +N more suffix appears when more than one incident or in-progress maintenance is active and links to the main status page. The line disappears automatically once every incident transitions to Resolved or Completed.

The daemon stores the current representative incident at /tmp/clhud-incidents.bin (408 bytes, seqlock-protected). If the daemon isn't running, the line simply doesn't appear — this degrades silently, like the git cache.

Autoupdate

The daemon keeps itself current. Roughly every 5 minutes it asks api.github.com for the latest release using a conditional GET (so most hits return 304 Not Modified). When a newer release exists, it downloads both binaries, verifies each against its .sha256 sidecar, swaps them into place, and restarts itself via launchd or systemd. For a few minutes after an update the client shows updated to vX.Y.Z under line 1.

Like everything else here, it degrades silently: if the daemon isn't running or a check fails, nothing happens and the installed version stays put.

Opt out. Install with CLAUDEHUD_NO_AUTOUPDATE=1, or set autoupdate=false in ~/.config/claudehud/config.

Pin a version. Install with CLAUDEHUD_VERSION=vX.Y.Z (persisted as pin=vX.Y.Z in the config). The daemon won't move off a pinned version.

Dev builds never self-update — only release binaries installed outside a target/ directory do. Windows autoupdate is not yet implemented; the daemon no-ops there.

Architecture

Two binaries in a Cargo workspace:

claudehud/
├── common/                 shared constants, FNV hash, seqlock read, git root detection, incidents layout
├── claudehud/              client binary — reads JSON from stdin, writes statusline to stdout
└── claudehud-daemon/       daemon — watches git repos reactively, polls status.claude.com, caches in mmap files

IPC: mmap + seqlock

Instead of spawning git on every render, the daemon holds per-repo status in memory-mapped files at /tmp/clhud-{fnv32(path)}.bin. The client reads directly from the mmap — no sockets, no syscalls beyond open + mmap.

Cache file layout (138 bytes):

OffsetSizeField
08u64 seqlock counter (even = stable, odd = write in progress)
81u8 dirty flag
91u8 branch name length
10128[u8; 128] branch name (UTF-8)

Registration: on first render for a new directory, the client writes a marker file to /tmp/clhud-watch/{hash} containing the absolute path. The daemon watches that directory via FSEvents (macOS) / inotify (Linux) and picks it up.

On Windows, cache files live under %LOCALAPPDATA%\claudehud\cache\ instead of /tmp/. The filename pattern (clhud-{hash}.bin) is identical.

Client read path:

  1. Hash the cwd with FNV-1a 32-bit
  2. Try open("/tmp/clhud-{hash}.bin") + mmap
  3. Seqlock read loop (spin on odd counter, fence on acquire)
  4. If file missing: write registration marker, fall back to direct git subprocess once

Daemon write path:

  1. Receive path from registrar
  2. Walk up to find .git root
  3. Watch {root}/.git/index and {root}/.git/HEAD via notify
  4. On FS event: re-run git status, seqlock-write to mmap file

Benchmark

Measured with hyperfine (500 runs, 20 warmup) on an M-series Mac, feeding a realistic JSON payload:

Benchmark 1: bash statusline.sh
  Time (mean ± σ):     436.9 ms ±   8.2 ms    [User: 312.1 ms, System: 98.4 ms]

Benchmark 2: claudehud (warm cache)
  Time (mean ± σ):       2.6 ms ±   0.7 ms    [User: 0.9 ms, System: 1.3 ms]

Summary
  claudehud ran ~168× faster than bash statusline.sh

The first render for a new directory hits the git fallback (~9ms). All subsequent renders use the mmap cache.

Both binaries combined weigh 878 KB vs the 8.1 KB bash script — 108× larger, 168× faster, net efficiency gain of ~1.6× (168 / 106).

Build

Requires Rust 1.70+ and Cargo.

cargo build --release

Binaries land at target/release/claudehud and target/release/claudehud-daemon.

On Windows, builds use the MSVC toolchain. The daemon's windows_subsystem = "windows" cfg only applies in --release mode — debug builds keep the console window so developers can see stdout/stderr.

# install
cp target/release/claudehud ~/.local/bin/
cp target/release/claudehud-daemon ~/.local/bin/

Configuration

Layout

Two render layouts: comfortable (default) and condensed. Set with the CLAUDEHUD_LAYOUT environment variable.

CLAUDEHUD_LAYOUT=condensed

Comfortable renders the HUD across multiple lines with full bars and a blank gap before rate limits:

Opus 4.7 (1M context) │ ✍️ 4% │ claudehud (main*)

current ○○○○○○○○○○   9% ⟳ 10:50am
weekly  ●○○○○○○○○○  12% ⟳ apr 25, 7:00pm

Condensed collapses everything onto a single line, with shorter rate-limit bars (4 dots) inline:

Opus 4.7 │ ✍️ 4% │ claudehud(main*) │ ○○○○ 5h 9% ⟳ 10:50am │ ○○○○ 7d 12% ⟳ apr 25, 7:00pm

On API billing (no rate_limits block from the harness), a 💰 segment with cost.total_cost_usd replaces the rate-limit rows:

Opus 4.7 (1M context) │ ✍️ 3% │ 💰 $0.13 │ claudehud (main*)

The segment is hidden when the field is missing or $0, and also hidden whenever rate_limits is present — plan users see an estimated cost from the harness, not actual spend, so showing it would be misleading. Tiered color: green < $1, yellow < $5, orange < $20, red ≥ $20.

Active incidents still render on their own line below row 1 in both layouts.

Unknown values (CLAUDEHUD_LAYOUT=foo) print a warning to stderr and fall back to comfortable.

Claude Code

Run claudehud install to wire the statusLine into ~/.claude/settings.json:

claudehud install            # prompts if a statusLine already exists
claudehud install --force    # overwrite without prompting
claudehud install --dry-run  # print the resulting JSON without writing

claudehud install --help lists all flags. Respects $CLAUDE_CONFIG_DIR and accepts --settings <path> to point at a non-default settings file.

To upgrade, run claudehud update — it re-invokes the official install script (idempotent, no-ops if already at the latest tag). Use claudehud update --check to compare versions without downloading.

Or set it by hand:

{
  "statusLine": {
    "command": "\"$HOME/.local/bin/claudehud\" render"
  }
}

Daemon (macOS launchd)

Create ~/Library/LaunchAgents/com.claudehud.daemon.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.claudehud.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/YOUR_USERNAME/.local/bin/claudehud-daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/claudehud-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/claudehud-daemon.err</string>
</dict>
</plist>
launchctl load ~/Library/LaunchAgents/com.claudehud.daemon.plist

Daemon (Linux systemd)

# ~/.config/systemd/user/claudehud-daemon.service
[Unit]
Description=claudehud git cache daemon

[Service]
ExecStart=%h/.local/bin/claudehud-daemon
Restart=always

[Install]
WantedBy=default.target
systemctl --user enable --now claudehud-daemon

Daemon (Windows Task Scheduler)

install.ps1 registers a per-user Task Scheduler entry named claudehud-daemon that runs at logon, hidden, with no admin required. The action invokes %LOCALAPPDATA%\Programs\claudehud\claudehud-daemon.exe and Task Scheduler restarts the daemon up to 3 times if it crashes.

Inspect or modify the registration:

schtasks /Query /TN claudehud-daemon /XML

Uninstall:

schtasks /Delete /TN claudehud-daemon /F

Dependencies

CrateUsed byPurpose
memmap2client + daemonmemory-mapped file I/O
serde + serde_jsonclientdeserialize Claude Code JSON payload
timeclientlocal timezone formatting
notifydaemonFSEvents/inotify filesystem watching
crossbeam-channeldaemonmulti-producer channel between registrar and watcher threads
ureqdaemonHTTPS client for status.claude.com
roxmltreedaemonAtom feed parser

common has no external dependencies.

Ver o original no GitHub

Bom para

Relacionados