agy-hud

Real-time statusline HUD plugin for Antigravity CLI (agy). Refreshes after every step with session info, detailed token breakdown, workspace context, and real account quota (matches /usage numbers).

CI verifies install + HUD render on macOS, Linux, Windows on every push — green badge above means it works.

简体中文

What it looks like

agy-hud supports two display modes for quota tracking: Table Mode (default) and Compact Mode (provider-grouped mini bars).

Table Mode (Default)

Useful for detailed side-by-side comparison of multiple models' quota.

⎇ main │ Gemini 3.5 Flash(L) │ Google AI Pro
⚿ 83.7k ↑4.8k ↓13.9k ⟳65.1k │ ⛁ 75.4k/1M [█░░░░░░░░░] 8% │ ⚡0 ✓0
1 GEMINI.md │ 2 hooks
  ─────────────────────────────────────────────────────────────────────────────────
  Gemini 3.5 Flash(M) [█████░]  80% ~3h22m │ Gemini 3.5 Flash(H) [█████░]  80% ~3h22m
  Gemini 3.5 Flash(L) [█████░]  80% ~3h22m │ Gemini 3.1 Pro(L)   [█████░]  80% ~3h22m
  Gemini 3.1 Pro(H)   [█████░]  80% ~3h22m │ Sonnet 4.6(Th)      [██░░░░]  40% ~6d4h
  Opus 4.6(Th)        [██░░░░]  40% ~6d4h  │ GPT-OSS 120B        [██░░░░]  40% ~6d4h
  ─────────────────────────────────────────────────────────────────────────────────

Compact Mode

Highly space-efficient. It embeds the current model's remaining quota directly on line 2, and displays provider-grouped mini progress bars.

⎇ main │ Claude Sonnet 4.6 │ Pro
⚿ 138.4M ↑6k ↓202k ⟳138.2M │ ⛁ 138.2M/1M [████░░░░░░] 40% │ ⚡42 ✓3 │ Quota: 100% ~5h
1 GEMINI.md │ 4 rules │ 1 MCPs │ 5 hooks
Anthropic: Son███ Opus█░░ │ Google: Flash███ Pro███ │ OpenAI: GPT█░░

Layout breakdown

Line 1 (identity): Resolved username/email (if enabled), Git branch, current model, plan tier.
Line 2 (resources): Compact token breakdown (↑in ↓out ⟳cache — cache hidden when zero), context window bar with percentage, step/task counts. In Compact Mode, also shows current model quota.
Line 3 (metadata): Project memory file, rules, MCPs, hooks — only non-zero items shown; entire line omitted when all are zero.
Quota rows: Account quota by model (matches /usage exactly) with reset countdowns. Durations ≥24h show days (e.g. ~6d4h), ≥10h drop minutes (e.g. ~12h).

Install

One command, in a normal shell (NOT inside an active agy session):

macOS / Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/install.sh)

Windows PowerShell:

irm https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/install.ps1 | iex

Windows CMD:

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/install.ps1 | iex"

This installer:

Cleanly re-installs the plugin (agy plugin uninstall + agy plugin install).
Downloads the HUD runtime to ~/.gemini/antigravity-cli/agy-hud-runtime/.
Writes statusLine.command into ~/.gemini/antigravity-cli/settings.json.

Open a fresh agy session — the HUD appears at the bottom of the terminal.

Idempotent — re-run the same command anytime to repair drift, upgrade, or clean stale files left by older versions.

Why not a-single `agy plugin install`?

agy plugin install only stages the declarative plugin marker (plugin.json); it never executes JavaScript and never touches settings.json. The HUD's statusLine command and renderer runtime are configured separately. install.sh does both pieces atomically.

For forks / mirrors

macOS / Linux:

AGY_HUD_REPO_RAW=https://raw.githubusercontent.com/your-fork/agy-hud/main \
AGY_HUD_REPO_URL=https://github.com/your-fork/agy-hud.git \
  bash <(curl -fsSL "$AGY_HUD_REPO_RAW/scripts/install.sh")

Windows PowerShell:

$env:AGY_HUD_REPO_RAW = 'https://raw.githubusercontent.com/your-fork/agy-hud/main'
$env:AGY_HUD_REPO_URL = 'https://github.com/your-fork/agy-hud.git'
irm "$env:AGY_HUD_REPO_RAW/scripts/install.ps1" | iex

Manual / advanced

If you prefer to run the steps yourself:

macOS / Linux:

agy plugin install https://github.com/icebear0828/agy-hud.git
bash <(curl -fsSL https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/bootstrap.sh)

Windows PowerShell:

agy plugin install https://github.com/icebear0828/agy-hud.git
$t = Join-Path $env:TEMP "agy-hud-bootstrap.js"
Invoke-WebRequest -Uri https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/bootstrap.js -OutFile $t -UseBasicParsing
node $t; Remove-Item $t

Windows CMD:

agy plugin install https://github.com/icebear0828/agy-hud.git
powershell -Command "Invoke-WebRequest -Uri https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/bootstrap.js -OutFile %TEMP%\agy-hud-bootstrap.js -UseBasicParsing"
node %TEMP%\agy-hud-bootstrap.js
del %TEMP%\agy-hud-bootstrap.js

Verify

After bootstrap:

# settings.statusLine should point at the runtime
cat ~/.gemini/antigravity-cli/settings.json | grep statusLine -A2

# Direct HUD invocation should print the HUD status lines
node ~/.gemini/antigravity-cli/agy-hud-runtime/runtime/bin/agy-hud.js

If quota rows show Antigravity token expired, refresh your agy login. That is not a bootstrap failure.

Windows PowerShell:

Get-Content "$env:USERPROFILE\.gemini\antigravity-cli\settings.json"
& "$env:USERPROFILE\.gemini\antigravity-cli\agy-hud-runtime\runtime\bin\agy-hud.cmd"

Diagnose

# Inspect token + quota cache state
node scripts/diagnose-auth.js

# Tail agy's own statusLine runner errors
ls -t ~/.gemini/antigravity-cli/log/cli-*.log | head -1 | xargs tail -50 | grep statusline

The most common failure mode is statusline_runner.go: failure N/30 — that means statusLine.command in settings.json points to a path that no longer exists. Re-run bootstrap.

Uninstall

macOS / Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/icebear0828/agy-hud/main/uninstall.sh)

Windows PowerShell:

irm https://raw.githubusercontent.com/icebear0828/agy-hud/main/uninstall.ps1 | iex

Windows CMD:

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/icebear0828/agy-hud/main/uninstall.ps1 | iex"

Or, if you have the repo cloned: bash uninstall.sh / .\uninstall.ps1.

This:

Clears settings.json statusLine (with .bak of the original).
Removes ~/.gemini/antigravity-cli/agy-hud-runtime/.
Removes the staged plugin (agy plugin uninstall agy-hud).
Cleans payload, error log, tmp token mirror, and quota cache files across all roots and tmp directories.

Configuration

Optional. Create agy-hud.config.json at the workspace root to override defaults. Without it the HUD uses runtime/agy-hud.config.json from the downloaded runtime:

{
  "theme": {
    "primary": "green",
    "secondary": "gray",
    "warning": "yellow",
    "critical": "red"
  },
  "display": {
    "quotaStyle": "table",
    "showTokenBar": true,
    "showBreadcrumbs": true,
    "showGitBranch": true,
    "showCurrentDir": true,
    "showUsername": false,
    "username": "",
    "breadcrumbCount": 3,
    "useNerdFonts": false,
    "columnWidth": 40
  },
  "thresholds": {
    "warning": 0.7,
    "critical": 0.9
  },
  "language": "auto"
}

Configuration fields

theme: Map of HUD component colors (primary, secondary, warning, critical). Supports standard terminal colors (green, gray, yellow, red, blue, magenta, cyan).
display:
- quotaStyle: "table" (default multi-column layout) or "compact" (inline quota + provider grouped mini bars).
- showTokenBar: Whether to display the token bar.
- showBreadcrumbs: Whether to display workspace file breadcrumbs.
- showGitBranch: Whether to display the current Git branch.
- showCurrentDir: Whether to display the base name of the current working directory.
- showUsername: Whether to display the username/email at the start of the HUD statusline.
- username: A custom string to override the resolved OS or login username/email.
- breadcrumbCount: Number of files to show in breadcrumbs.
- useNerdFonts: Set to true to use premium developer icons from Nerd Fonts.
- columnWidth: Max column width for the quota table layout (defaults to 40).
thresholds: Threshold values (0.0 to 1.0) for displaying quota warning and critical usage colors.
language: Lang preference ("auto", "en", "zh").

File structure

agy-hud/
├── plugin.json                # {"name":"agy-hud"} — agy plugin marker
├── gemini-extension.json      # required by agy's remote-install validator
├── runtime/                   # downloaded by bootstrap to ~/.gemini/.../agy-hud-runtime/runtime/
│   ├── bin/agy-hud.js         # statusLine entry (stdin JSON → ANSI HUD)
│   ├── config-wizard.js       # configuration wizard (--config)
│   ├── config.js              # config loader & writer
│   ├── encoding.js            # console encoding & Unicode detector
│   ├── parser.js              # scans workspace metadata & session transcript
│   ├── paths.js               # cross-platform path resolution helpers
│   ├── quota.js               # SWR quota orchestrator
│   ├── quota/                 # quota & auth submodules (PR #62)
│   │   ├── cache.js           # atomic JSON caching (v3 schema)
│   │   ├── cloud.js           # API HTTP clients ( OIDC userinfo auth email)
│   │   ├── models.js          # quota normalizer & window merging
│   │   └── token.js           # cross-platform OAuth token discovery
│   ├── renderer.js            # HUD layout orchestrator
│   ├── renderer/              # ANSI rendering submodules (PR #58)
│   │   ├── format.js          # colors, abbreviator, duration formatting
│   │   ├── lang.js            # internationalization (zh/en auto-detection)
│   │   └── quota-render.js    # column bars & single-row columns (PR #61)
│   ├── statusline-installer.js# writes settings.json statusLine settings
│   ├── uninstall.js           # cleans and purges runtime files
│   └── update-checker.js      # checks for new GitHub releases
├── scripts/
│   ├── install.sh             # one-command installer — macOS/Linux
│   ├── install.ps1            # one-command installer — Windows PowerShell
│   ├── bootstrap.sh           # repair-only entry (called by install.sh)
│   ├── bootstrap.js           # actual download + configure logic
│   ├── configure-utf8.ps1     # optional Windows UTF-8 profile + Git encoding helper
│   ├── verify-display.js      # E2E: install + bootstrap + PTY-spawn agy + assert HUD
│   └── diagnose-auth.js
├── tests/unit/                # modular unit tests (node --test)
├── .github/workflows/e2e.yml  # cross-platform CI matrix
└── release.sh                 # npm test → E2E gate → zip → gh release

Cross-platform notes

Windows UTF-8 helper: If your terminal is on a non-UTF-8 codepage and you want Unicode bars/borders by default, run:

irm https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/configure-utf8.ps1 | iex

This appends a guarded UTF-8 encoding block to your PowerShell profile and sets Git's global UTF-8 filename/log options. It is idempotent and safe to re-run. Restart PowerShell after it finishes.

Windows token refresh: Antigravity CLI stores OAuth refresh_token + access_token in Credential Manager (gemini:antigravity / LegacyGeneric:target=gemini:antigravity). The HUD prefers a short-lived agy-hud-token.json mirror in tmp. When the fast path only sees a missing/expired file token, it triggers a detached background read; the next render uses the refreshed token. agy-hud does not swap RT for access tokens — if the Credential Manager access token is expired, refresh agy's login first.

File token fallback paths (searched in order):

~/.gemini/antigravity-cli/antigravity-oauth-token
$XDG_DATA_HOME/antigravity-cli/antigravity-oauth-token
$APPDATA/antigravity-cli/antigravity-oauth-token
$LOCALAPPDATA/antigravity-cli/antigravity-oauth-token

Verified by CI

Every push to main runs .github/workflows/e2e.yml against a 3-OS matrix:

OS	install.sh runs	bootstrap writes settings.json	HUD command renders status lines
ubuntu-latest	✅	✅	✅
macos-latest	✅	✅	✅
windows-latest	✅	✅	✅

Each run uploads (14-day retention):

Artifact	Per-OS	Contents
`e2e-<os>`	all 3	`e2e-report.json` (diagnostic: `ok`, `hudVisible`, `staleCleaned`, …) + `agy-hud-pty-*.log` (raw ANSI bytes — `cat` to see the HUD render with colors)
`hud-screenshot-<os>`	ubuntu + macos	`hud-ascii-<os>.png` + `hud-unicode-<os>.png` rendered via charm.sh `freeze`. PNG visual evidence — download and open.

CI runs in no-auth mode: it asserts the standalone HUD command renders the status lines. The full "HUD visible inside a live agy session with model-step trigger" check runs on dev machines (with real OAuth) via release.sh's built-in E2E gate.

Known issues

Windows PNG screenshot: every CI run uploads hud-ascii-*.png and hud-unicode-*.png for macOS + Linux via charm.sh freeze. Windows is skipped — freeze v0.2.2 errors No input for every invocation form (positional file, --execute, UTF-8 file via .WriteAllText) we tried; it's an upstream Windows bug. Windows reviewers still get the raw ANSI bytes via the e2e-windows-latest artifact (cat it to see the HUD with colors).

Note for Windows users: The HUD auto-detects your active console codepage. If it's a non-UTF-8 codepage like cp936 (GBK) or cp1252, the progress bar will fall back to ASCII characters (#) to prevent encoding corruption.

If you force Unicode rendering (e.g. by setting display.unicode: true in your configuration) while the active codepage is not UTF-8, you may see garbled text or ? replacement characters.

How to enable beautiful Unicode progress bars and borders on Windows:

PowerShell helper (Recommended): Run irm https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/configure-utf8.ps1 | iex, then restart PowerShell.

Per Session: Run chcp 65001 once in your Command Prompt / PowerShell window before opening agy.

System-wide UTF-8 (Permanent):

Go to Windows Settings -> Time & language -> Language & region -> Administrative language settings.

Click Change system locale.

Check "Beta: Use Unicode UTF-8 for worldwide language support" and restart your computer.

This forces all terminal sessions to use UTF-8 (cp65001) natively.

License

MIT

Name		Name	Last commit message	Last commit date
.antigravity/rules		.antigravity/rules
.github/workflows		.github/workflows
docs		docs
runtime		runtime
scripts		scripts
skills/hud-config		skills/hud-config
tests/unit		tests/unit
.gitignore		.gitignore
README.md		README.md
README_zh.md		README_zh.md
gemini-extension.json		gemini-extension.json
package-lock.json		package-lock.json
package.json		package.json
plugin.json		plugin.json
release.sh		release.sh
uninstall.ps1		uninstall.ps1
uninstall.sh		uninstall.sh

Navigation Menu

Repository files navigation

agy-hud

What it looks like

Table Mode (Default)

Compact Mode

Layout breakdown

Install

Why not a-single `agy plugin install`?

For forks / mirrors

Manual / advanced

Verify

Diagnose

Uninstall

Configuration

Configuration fields

File structure

Cross-platform notes

Verified by CI

Known issues

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

agy-hud

What it looks like

Table Mode (Default)

Compact Mode

Layout breakdown

Install

Why not a-single agy plugin install?

For forks / mirrors

Manual / advanced

Verify

Diagnose

Uninstall

Configuration

Configuration fields

File structure

Cross-platform notes

Verified by CI

Known issues

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Why not a-single `agy plugin install`?