A heads-up display for Claude Code.
Real-time statusline with Ollama Cloud + Anthropic dual-mode rendering, in ~76ms per tick.
/plugin marketplace add nicolaslima/ohud
/plugin install ohud
/ohud setup
Restart Claude Code. The HUD appears below every assistant message.
Why three commands and not two?
/plugin installregisters slash commands (/ohud doctor, etc) but does not activate the statusline./ohud setupdetects your runtime (Node/Bun) and writes the actual statusline binding to~/.claude/settings.json. This is required because Claude Code does not yet honorplugin.json:statusLinedeclarations — see docs/explanation/design-decisions.md for the full story.Then:
/ohud configureto pick a preset (Full / Essential / Minimal)./ohud doctorif anything looks off.
[glm-5:cloud ⚡ 1T] │ ohud │ git:(main *↑3 ↓1) │ effort:max
Context ████░░░░░░ 43% │ API ⏱ 4m 12s
◐ Edit: project.ts │ ✓ Read ×42 │ ✓ Bash ×17
▸ implement split-TTL cache (3/9)
RAM ███████░░░ 71% (11.4 GB / 16.0 GB)
Five lines, each reading from the JSON Claude Code pipes via stdin, the session transcript JSONL, an optional Ollama probe, and your git working copy. Lines you don't want hide via flags — turn off showMemoryUsage and that bottom line vanishes.
| Mode | Trigger | Lines unlocked |
|---|---|---|
| Ollama | model.id ends in :cloud OR matches a model from your local Ollama daemon at localhost:11434 |
[name ⚡ 1T] badge with parameter size, API ⏱ Xm Ys consumption |
| Anthropic | anything else (default fallback) | Usage 5h/7d rate-limit windows, Cost $X.YZ (estimate or native), cache N% prompt-cache freshness |
Common to both: project path + git, context bar, tools/agents/todos, environment counts, memory, duration, effort level.
Detection happens silently — no warnings, no flags to set. Wrong mode? /ohud doctor shows what got resolved and why.
Spawn-per-tick. Every ~300ms during an active session, Claude Code spawns dist/index.js, pipes a JSON blob to stdin, ohud reads it + the transcript + an Ollama probe (split-TTL cached: 5s daemon, 120s models), runs 12 line renderers in parallel, writes to stdout, exits. No daemon, no in-memory state across ticks, no cleanup logic.
Watch the lifecycle animated: see docs/_assets/spawn-per-tick.svg (loops every 6s on GitHub).
Median tick: 76.9ms — 25.6% of the 300ms budget. Cold-start measured with OHUD_PROFILE=1 on Node 22 / M1 macOS. ohud is monomorphic on the hot path (no try/catch in render loop, no allocations in the inner per-line code), and the Ollama probe uses a split-TTL cache that almost always hits. Full breakdown: docs/explanation/300ms-budget.md.
Documentation follows the Diátaxis methodology — pick the section that matches what you need right now:
| Need | Section |
|---|---|
| 🟢 Just installed, walk me through it | Tutorial: Getting Started |
| 🛠 I have a specific problem | How-To Guides (5 recipes) |
| 📚 What does flag X do? | Reference (config, env vars, stdin, line modules, slash commands) |
| 💡 Why is it shaped this way? | Explanation (architecture, design decisions, 300ms budget) |
Full index: docs/README.md.
- Configuration: docs/reference/config-schema.md
- Slash commands: docs/reference/slash-commands.md
- All 12 line modules: docs/reference/line-modules.md
- Customize colors: docs/how-to/customize-colors-and-glyphs.md
- Diagnose problems: docs/how-to/diagnose-blank-statusline.md
| Item | Minimum | Recommended |
|---|---|---|
| Claude Code | any recent version | latest |
| Runtime | Node.js ≥18 | Bun |
| Ollama (optional) | any version | ollama serve running on localhost:11434 |
| Terminal | ANSI 16-color | truecolor + UTF-8 |
ohud has zero runtime dependencies — only Node/Bun stdlib + fetch + AbortController. Bundle is one ~43KB JS file in dist/. See zero-deps rationale.
Statusline blank? Wrong mode showing? Always start with:
/ohud doctor
It prints version, runtime, resolved bundle path, live probe state, current mode, and which config flags are actually consumed (vs DEAD FLAG placeholders). Plus the last 5 errors from ~/.claude/plugins/ohud/last-errors.log.
Then jump to docs/how-to/diagnose-blank-statusline.md — a flowchart for the most common failure modes.
git clone https://github.com/nicolaslima/ohud
cd ohud
bun install
bun test # 103 tests
bun run build # rebuild dist/index.jsdist/ is committed intentionally — marketplace install is git clone with no postinstall. CI guards drift via bun run build && git diff --exit-code dist/. See why dist/ is committed.
To add a 13th line renderer, follow the recipe at docs/how-to/add-a-new-line-module.md.
Visual layout inspired by claude-hud by Jarrod Watts. ohud is an independent reimplementation, not a fork — different goals (stateless spawn-per-tick, dual-mode auto-detection, zero deps).
MIT. See LICENSE.