understatus

A calm, unobtrusive statusline addon for Claude Code — live CPU, memory, battery, disk, network, and AI session info in a permanent bottom bar that stays out of your way.

Why

Most statusline widgets are noisy. understatus is designed around one principle: permanent visibility without distraction.

Calm glyph theme — load stages render as ○ ▁ ▄ ▆ ◆. Color touches the glyph only; numeric values stay uncolored. Labels and separators are dimmed. At ≥90% CPU the critical glyph ◆ breathes slowly in restrained terracotta (#b87848 ↔ #7a5030) — not red, not flashing.
Reactive CPU — every render takes two snapshots ~25 ms apart and computes true instantaneous CPU% across all cores. No stale load-average guessing.
Non-destructive chaining — understatus install detects your existing statusLine.command, preserves it in config, and chains it. uninstall restores byte-for-byte. Your current setup is never lost.

macOS only. Apple Silicon (arm64) + Intel (x86_64). Linux is not supported.

Install

Homebrew (recommended)

brew install ictechgy/understatus/understatus

The formula lives in the tap ictechgy/understatus (repo: ictechgy/homebrew-understatus).

Cargo

cargo install understatus

Requires Rust 1.75+.

npm

npm install -g understatus

The npm package shells out to the prebuilt macOS binary for your architecture (arm64 / x64). macOS only.

From source

git clone https://github.com/ictechgy/understatus.git
cd understatus
cargo build --release
# binary at ./target/release/understatus

Setup

Install into Claude Code

understatus install

This patches ~/.claude/settings.json non-destructively:

Reads your current statusLine.command (if any).
Saves it as chain_command in ~/.config/understatus/config.toml.
Replaces statusLine.command with the understatus binary path.
Injects "refreshInterval": 5 (sourced from config.toml [refresh].interval_seconds).

Uninstall

understatus uninstall

Restores statusLine.command and refreshInterval to their exact pre-install state. If refreshInterval was absent before install, the key is deleted.

⚠️ Global side-effect: `refreshInterval = 5`

understatus install writes "refreshInterval": 5 into settings.json. This value applies to the entire statusLine subsystem — not just understatus:

understatus itself spawns as a new process every 5 seconds.
Any chained command (e.g. lterm-omc-hud.mjs) is also re-executed every 5 seconds.

To decouple heavy chain children, understatus caches their stdout via chain_cache_ttl_seconds (default 10 s). The chained child re-spawns at most once per TTL — not every 5 s.

To save battery on laptops, raise the interval:

# ~/.config/understatus/config.toml
[refresh]
interval_seconds = 10   # default: 5

Note: increasing interval_seconds proportionally slows the terracotta breath animation. Adjust pulse_period_seconds accordingly to keep it smooth (pulse_period / interval >= 6).

understatus uninstall reverts refreshInterval precisely — no residue left behind.

Configuration

File: ~/.config/understatus/config.toml
All keys are optional; omitting a key uses its default.

Key	Default	Description
`[cpu] sample_window_ms`	`25`	Interval (ms) between the two CPU snapshots. Larger = less noise, more latency.
`[cpu] load_glyphs`	`["○","▁","▄","▆","◆"]`	Glyphs for idle→critical load stages. Color is applied to the glyph only. To restore the original emoji theme: `["😌","🙂","😅","🥵","🔥"]`.
`[pulse] pulse_on_threshold`	`90`	CPU% at which the critical glyph starts breathing.
`[pulse] pulse_off_threshold`	`80`	CPU% below which the breath turns off (hysteresis).
`[pulse] pulse_period_seconds`	`30`	One full breath cycle in seconds. Keep `period / interval_seconds >= 6` for smooth animation.
`[pulse] pulse_style`	`"calm"`	`"calm"` = fixed glyph shape + terracotta brightness breath (hue never changes). `"bold"` = legacy style.
`[chain] chain_command`	`""`	Populated by `install`. The command that runs alongside understatus.
`[chain] order`	`"self_first"`	`"self_first"` or `"chain_first"` — which output appears on the left.
`[chain] chain_cache_ttl_seconds`	`10`	How long (s) to cache the chained command's stdout before re-spawning it.
`[chain] chain_timeout_ms`	`500`	Max ms to wait for the chained command. On timeout, cached or empty output is used.
`[display] max_width`	`80`	Maximum character width. Lower-priority segments are omitted when exceeded.
`[display] show_model`	`true`	Show Claude model name.
`[display] show_cost`	`true`	Show cumulative session cost.
`[display] show_context`	`true`	Show context usage %. Omitted automatically when null.
`[display] show_git`	`true`	Show git branch (derived from `workspace.git_worktree` / repo).
`[display] show_battery`	`true`	Show battery (IOKit, 30 s TTL cache). Silently omitted on desktops.
`[display] show_disk`	`true`	Show disk usage via `statfs("/")`.
`[display] show_network`	`true`	Show network throughput (getifaddrs counter delta). First render has no delta — omitted silently.
`[color] mode`	`"auto"`	`"auto"` \| `"truecolor"` \| `"256"` \| `"none"`. Respects `NO_COLOR`.
`[color] band_tints`	see below	Five hex colors for idle→critical glyph tint. Defaults: cool blue-grey ladder + terracotta at index 4.
`[color] pulse_palette`	`["#b87848","#7a5030"]`	High/low terracotta brightness for the breath animation.
`[color] label_color`	`"#6b7280"`	Dimmed color for labels, units, arrows, and git marker.
`[color] separator`	`" · "`	Segment separator string.
`[color] separator_color`	`"#3b4048"`	Color for separator and HUD seam.
`[color] hud_seam`	`"│"`	Character placed between understatus output and the chained command output.
`[refresh] interval_seconds`	`5`	Value written to `settings.json` as `refreshInterval`. ⚠️ Global side-effect — see above.

Default band_tints (cool blue-grey brightness ladder, warm terracotta only at critical):

band_tints = ["#5a6878", "#6d8296", "#86a0b4", "#9fbfce", "#b87848"]

How it works

Claude Code  (every refreshInterval seconds)
   │  stdin: one JSON line
   ▼
understatus binary  (new process per call — no daemon, no state files, no locks)
   ├─ parse stdin  → ClaudeInput
   ├─ double-sample CPU  → cpu_percent (0–100%, average across all cores)
   │     on failure → loadavg fallback: min(load1 / ncpu × 100, 100)
   ├─ memory (host_statistics64)
   ├─ battery (IOKit, 30 s TTL cache)        ← omitted on desktops
   ├─ disk    (statfs("/"))
   ├─ network (getifaddrs counter delta)     ← omitted on first render
   ├─ glyph + band tint (color on glyph only)
   │   at ≥90% CPU → terracotta brightness breath on ◆
   ├─ chain_command child (TTL cache + 500 ms timeout)
   └─ compose → stdout (single newline)

CPU measurement: Two /proc-equivalent snapshots are taken ~25 ms apart within the same process invocation. The delta gives true instantaneous utilization — not a smoothed load average. If the syscall fails (rare), loadavg serves as a silent fallback.

Glyph + tint design: band_tints[0..3] are cool blue-grey values of increasing brightness (idle to high load). band_tints[4] is the lone warm color — terracotta — reserved for the critical stage. Only the glyph character receives color; all numeric values and labels stay uncolored.

Terracotta breath: When CPU stays at ≥90%, the ◆ glyph cycles between pulse_palette[0] (brighter terracotta) and pulse_palette[1] (darker terracotta) over pulse_period_seconds. Hue never shifts — only brightness. This is the "calm" pulse style.

CLI Support Matrix

CLI	Status	Notes
Claude Code	✅ Full support	Custom `statusLine.command`, stdin JSON, `refreshInterval` (default 5 s) — all supported.
Gemini CLI	⏳ Stub / forward-looking	`/footer` and `/statusline` expose built-in items only; custom commands not yet supported (open issue).
Codex CLI	⏳ Stub / forward-looking	`[tui].status_line` is a fixed built-in; custom commands not yet supported (open issue).

Gemini and Codex integration is documented and stubbed (CliAdapter trait planned) but not yet functional — those CLIs do not currently expose a custom statusline command hook.

Platform

macOS only. Uses host_processor_info, host_statistics64, and IOPSCopyPowerSourcesInfo — all macOS-specific APIs.
Apple Silicon (arm64) + Intel (x86_64). Tested on macOS arm64 with a 12-core Apple Silicon chip.
Linux: builds may succeed, but CPU double-sampling degrades silently to loadavg fallback. Not a supported target.
Rust edition 2021, MSRV 1.75+.

License

MIT — see LICENSE.

한국어 안내

macOS용 AI 코딩 CLI statusline 애드온입니다. CPU%, 메모리, 배터리, 디스크, 네트워크, AI 세션 정보(모델명·비용·컨텍스트)를 Claude Code 하단 표시줄에 조용하고 자연스럽게 표시합니다.

주요 특징

절제된 글리프 테마 — 부하 단계: ○ ▁ ▄ ▆ ◆. 색은 글리프에만, 숫자 값은 무색, 라벨·구분자는 디밍. CPU ≥90%에서만 ◆가 테라코타 명도 호흡(#b87848↔#7a5030).
반응형 CPU — 매 렌더마다 두 스냅샷(~25ms 간격) 직접 측정. loadavg 아님.
비파괴 설치 — 기존 statusLine.command를 체이닝으로 보존하고 정확히 복원.

설치

# Homebrew
brew install ictechgy/understatus/understatus

# Cargo
cargo install understatus

# npm
npm install -g understatus

Claude Code에 적용

understatus install   # ~/.claude/settings.json 패치 (비파괴)
understatus uninstall # 원상 복원

⚠️ install은 settings.json에 "refreshInterval": 5를 전역 주입합니다. 체이닝된 기존 명령도 5초마다 재실행 대상이 됩니다. 배터리 절약이 필요하면 config.toml에서 interval_seconds = 10으로 올리세요.

설정 파일: ~/.config/understatus/config.toml (없으면 모두 기본값)

기존 이모지 테마 복원: config.toml에서 load_glyphs = ["😌","🙂","😅","🥵","🔥"]

macOS 전용 · Apple Silicon(arm64) + Intel(x86_64) · Rust 1.75+ · MIT 라이선스

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github/workflows		.github/workflows
docs		docs
homebrew		homebrew
npm		npm
src		src
tests		tests
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

understatus

Why

Install

Homebrew (recommended)

Cargo

npm

From source

Setup

Install into Claude Code

Uninstall

⚠️ Global side-effect: `refreshInterval = 5`

Configuration

How it works

CLI Support Matrix

Platform

License

한국어 안내

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

understatus

Why

Install

Homebrew (recommended)

Cargo

npm

From source

Setup

Install into Claude Code

Uninstall

⚠️ Global side-effect: refreshInterval = 5

Configuration

How it works

CLI Support Matrix

Platform

License

한국어 안내

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

⚠️ Global side-effect: `refreshInterval = 5`

Packages