---

Gemini CLI HUD is a real-time status monitor that renders a sticky status bar at the bottom of your terminal during Gemini CLI sessions. It provides critical observability into your AI agent's internal state — model, context usage, tool calls, and more — without interfering with your workflow.

Screenshots

────────────────────────────────────── gemini-cli-hud ──────────────────────────────────────
 gemini-3-flash Pro xulei0331 │ git:(main) │ 4 GEMINI.md 2 ext │ Ctx: ██░░░░░░ 3% (28K/1.0M) 20 tok/s
 ↑84K ↓1K $0.013 │ Mem: 80% (19.1/24.0GB) │ Session: 5m3s

Features

• Bottom-Sticky HUD: Renders at the terminal bottom using DECSTBM scroll regions, staying visible while you work.
• Real-Time Context Usage: Progress bar showing context window consumption percentage.
• Token Throughput: Displays tokens/sec rate (e.g., 1.2K tok/s) next to the context bar.
• Cost Estimation: Real-time API cost tracking with input/output breakdown: ↑420K ↓52K $0.021.
• Subscription & Account Display: Shows subscription tier (Pro/Free/Ultra) and account name next to the model, with OAuth/API fallback.
• Active Model Tracking: Displays the current model (e.g., gemini-3-flash).
• Tool Observability: Claude-HUD style tool display: ✓ Read ×8 | ✓ Bash ×4.
• GEMINI.md Counter: Shows how many GEMINI.md files are loaded (project + global + extensions).
• Extensions Counter: Shows installed Gemini CLI extensions count.
• Active Skill Tracking: Displays the currently activated skill/extension.
• Session Timer: Elapsed time since session start.
• Git Integration: oh-my-zsh style branch display: git:(main*) with ahead/behind upstream counts.
• System Memory Monitor: Real-time memory usage (macOS vm_stat with cross-platform fallback).
• Token Cache Breakdown: Shows cached content tokens separately: ↑420K ↓52K ⚡20K $0.021.
• Task Progress Tracking: Detects markdown checklists (- [x]/- [ ]) and numbered steps in model responses, displaying real-time task completion: Tasks: 2/5.
• Multi-Session Support: Each Gemini CLI instance gets its own isolated HUD daemon.
• Session Cleanup: Automatically resets terminal scroll region on session exit.
• Configurable Layout: Choose which modules to display, their order, and toggle individual elements via ~/.gemini/hud.json.
• Presets: Three built-in presets — full, essential, minimal — for quick setup.
• Responsive Layout: Modules wrap to multiple lines on narrow terminals instead of truncating mid-text.
• Title Bar Fallback: Also sets the terminal title (OSC 0) as a secondary display.

Installation

Quick Install (from GitHub)

gemini extensions install https://github.com/yideng-xl/gemini-cli-hud

Manual Install

1. Clone and build:

   git clone https://github.com/yideng-xl/gemini-cli-hud.git
   cd gemini-cli-hud
   pnpm install
   pnpm run build
   

2. Install to Gemini extensions directory:

   bash install.sh
   

3. Restart Gemini CLI. The HUD appears automatically.

Configuration

Create ~/.gemini/hud.json to customize the HUD. All fields are optional — missing fields use defaults. Changes take effect on the next hook event (no restart needed).

Presets

Three built-in presets for quick setup:

Preset	Modules	Description
full (default)	model, git, meta, skill, context, tools, cost, memory, task, session	Everything visible
essential	model, git, context, tools, task, session	Core info + git + tasks, no meta/skill/cost
minimal	model, context, session	Bare minimum

{ "preset": "essential" }

Recommended Configurations

Full config with all options (default) — save to ~/.gemini/hud.json:

{
  "preset": "full",
  "modules": ["model", "git", "meta", "skill", "context", "tools", "cost", "memory", "task", "session"],
  "display": {
    "showModel": true,
    "showAuth": true,
    "showContext": true,
    "showTokenRate": true,
    "showTools": true,
    "showCost": true,
    "showSkill": true,
    "showSession": true,
    "showMeta": true,
    "showGit": true,
    "showMemory": true,
    "showTask": true
  },
  "language": "en"
}

Developer — focus on context & tools, skip cost:

{
  "preset": "essential",
  "display": { "showTokenRate": true }
}

─── gemini-cli-hud ───
 gemini-3-flash Pro user │ git:(main) │ Ctx: ████░░ 42% (420K/1.0M) 1.2K tok/s
 ✓ Read ×8 | ✓ Bash ×4 │ Session: 12m

Cost-conscious — track spending, hide meta:

{
  "modules": ["model", "git", "context", "tools", "cost", "session"],
  "display": { "showMeta": false, "showSkill": false }
}

─── gemini-cli-hud ───
 gemini-3-flash Pro user │ git:(main) │ Ctx: ████░░ 42% (420K/1.0M)
 ✓ Read ×8 | ✓ Bash ×4 │ ↑420K ↓52K $0.021 │ Session: 12m

Minimal — just model & context bar:

{ "preset": "minimal" }

─── gemini-cli-hud ───
 gemini-3-flash Pro user │ Ctx: ████░░ 42% (420K/1.0M) │ Session: 12m

Minimal + cost — compact but cost-aware:

{
  "preset": "minimal",
  "display": { "showCost": true },
  "modules": ["model", "context", "cost", "session"]
}

─── gemini-cli-hud ───
 gemini-3-flash Pro user │ Ctx: ████░░ 42% (420K/1.0M) │ ↑420K ↓52K $0.021 │ Session: 12m

Available Modules

Module	What it shows
model	Model name + subscription tier + account (e.g., gemini-3-flash Pro xulei0331)
meta	GEMINI.md file count + extensions count
skill	Currently active skill/extension
context	Context window progress bar + percentage + token rate
tools	Tool call counts: ✓ Read ×8 | ✓ Bash ×4
cost	Input/output tokens + estimated cost: ↑420K ↓52K $0.021
git	Git branch in oh-my-zsh style: git:(main*) with ↑3 ↓1
memory	System memory: Mem: 80% (19.1/24.0GB)
task	Task progress from model responses: Tasks: 2/5 (detects - [x]/- [ ] checklists and numbered steps)
session	Elapsed time since session start

Display Flags

Fine-grained control over sub-elements within modules:

Flag	Default	Controls
showModel	true	Model name display
showAuth	true	Subscription tier + account (falls back to OAuth/API)
showContext	true	Context progress bar
showTokenRate	true	Token throughput (tok/s)
showTools	true	Tool call statistics
showCost	true	Cost estimation
showSkill	true	Active skill name
showSession	true	Session timer
showMeta	true	GEMINI.md & extensions count
showGit	true	Git branch and status
showMemory	true	System memory usage
showTask	true	Task progress tracking

Language

Value	Language
"en"	English (default)
"zh"	简体中文 — 上下文: 会话: 词元/秒 扩展

{ "language": "zh" }

Subscription & Account Display

By default, the HUD reads only local files (~/.gemini/google_accounts.json) to show your account name. No network requests, no token refresh, no authorization popups. If no account file exists, the module is simply hidden — all other HUD features work normally.

If you want to see your precise subscription tier (Pro / Free / Ultra), you can opt in to the quota API by adding "quotaApi": true to your config:

{ "quotaApi": true }

What this does: reads existing Gemini CLI OAuth credentials (from ~/.gemini/oauth_creds.json) and calls Google's loadCodeAssist API to fetch your subscription tier. HUD never triggers new authorization flows — it only reuses tokens that Gemini CLI has already obtained. If credentials are missing or expired, the module gracefully falls back to local-only mode.

Privacy

The HUD collects zero user data. Everything stays on your machine:

• Account name: Read from ~/.gemini/google_accounts.json (local file created by Gemini CLI)
• Subscription tier (opt-in only): Fetched via Google API using your existing Gemini CLI credentials
• Session count: Stored locally in ~/.gemini/hud-star.json (for the one-time star prompt)
• No telemetry, no analytics, no data sent to third parties

Architecture

┌─────────────────────────────────────────┐
│ Gemini CLI (Ink rendering)              │  Scroll region: rows 1 to N-K
│ > your input                            │
│                                         │
├──────────── gemini-cli-hud ─────────────┤  Row N-K+1: separator
│ model │ meta │ Ctx: ██░░ │ tools │ time │  Row N-K+2..N: content
└─────────────────────────────────────────┘

• Daemon (daemon.js): Background process that maintains HUD state (model, tokens, tools, skill). Receives events via Unix socket. Never writes to the terminal.
• Hook (hook.js): Invoked synchronously by Gemini CLI on each event (SessionStart, AfterModel, AfterTool). Forwards events to daemon, receives rendered HUD content, and writes to /dev/tty using DECSTBM. Only the hook touches the terminal — this avoids race conditions with Ink.

How It Works

Event	What Happens
SessionStart	Hook starts daemon (if needed), resets state
AfterModel	Captures model name, prompt token count, context size, calculates token rate and cost
AfterTool	Tracks tool usage counts, detects activate_skill events
SessionEnd	Resets DECSTBM scroll region, cleans up socket file

The hook renders the HUD synchronously during each event — no background timers, no polling, no race conditions with Gemini CLI's Ink engine.

Known Limitations

• Terminal resize: HUD updates on the next hook event after resize (not instantly), to avoid race conditions with Ink.
• Ink overwrites: If Gemini CLI clears the screen (\x1b[J), the HUD may briefly disappear until the next event redraws it.
• Cost estimation: Based on published Gemini API pricing; actual billing may vary. Free-tier users are not charged.

Roadmap

1. Native Statusline API: If Google exposes a UI injection API for extensions, migrate to it for perfect integration.
2. Todo/Task Progress: Done in v0.6.0 — Detects markdown checklists and numbered steps from model responses.
3. Zero Dependency Migration: Done in v0.6.0 — Removed React/Ink runtime dependency; zero production dependencies.

Inspiration

This project is inspired by Claude HUD by Jarrod Watts. We wanted to bring the same level of observability to the Gemini CLI ecosystem.

Contributors

• yideng-xl — Creator and maintainer
• Gemini (Gemini 3 Flash / Pro) — AI pair programmer & co-architect. Built the initial daemon + hook architecture, title-bar prototype, and early DECSTBM explorations.
• Claude (Claude Opus 4.6) — AI pair programmer & co-architect. Implemented bottom-sticky DECSTBM rendering, responsive module layout, context tracking, tool display, GEMINI.md counting, skill tracking, and resize handling.

License

MIT