{
  "markdown": "# agy-hud\n\n[![E2E](https://github.com/icebear0828/agy-hud/actions/workflows/e2e.yml/badge.svg?branch=main)](https://github.com/icebear0828/agy-hud/actions/workflows/e2e.yml)\n[![Release](https://img.shields.io/github/v/release/icebear0828/agy-hud)](https://github.com/icebear0828/agy-hud/releases/latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)\n\n> 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).\n>\n> CI verifies install + HUD render on **macOS, Linux, Windows** on every push — green badge above means it works.\n\n[简体中文](./README_zh.md)\n\n---\n\n## What it looks like\n\nagy-hud supports two display modes for quota tracking: **Table Mode** (default) and **Compact Mode** (provider-grouped mini bars).\n\n### Table Mode (Default)\nClean 2x2 provider quota overview (Google 5h/week & Claude 5h/week) matching your active subscription.\n\n```\ndiangelosabri@gmail.com │ agy-hud │ ⎇ main │ Gemini 3.7 Flash(M) │ Google AI Pro\n⚿ Tokens 172.3k (in: 2.8k, out: 35.3k, cache: 134.3k) │ ⛁ 129.2k/1M [█░░░░░░░░░] 12%\n1 MEMORY.md │ 1 hooks\n  ─────────────────────────────────────────────────────────────────────────────────\n  Google 5h   [█████░]  87% ~22m   │ Claude 5h   [██████] 100% ~4h59m\n  Google week [████░░]  74% ~4d3h  │ Claude week [██████] 100% ~6d23h\n```\n\n### Compact Mode\nHighly space-efficient. It embeds the current model's remaining quota directly on line 2, and displays provider-grouped mini progress bars.\n\n```\n⎇ main │ Claude Sonnet 4.6 │ Pro\n⚿ 138.4M ↑6k ↓202k ⟳138.2M │ ⛁ 138.2M/1M [████░░░░░░] 40% │ ⚡42 ✓3 │ Quota: 100% ~5h\n1 GEMINI.md │ 4 rules │ 1 MCPs │ 5 hooks\nAnthropic: Son███ Opus█░░ │ Google: Flash███ Pro███ │ OpenAI: GPT█░░\n```\n\n### Layout breakdown\n- **Line 1** (identity): Resolved username/email (if enabled), Git branch, current model, plan tier.\n- **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.\n- **Line 3** (metadata): Project memory file, rules, MCPs, hooks — **only non-zero items shown**; entire line omitted when all are zero.\n- **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`).\n\n---\n\n## Install\n\nOne command, in a normal shell (NOT inside an active `agy` session):\n\n**macOS / Linux**:\n```bash\nbash <(curl -fsSL https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/install.sh)\n```\n\n**Windows PowerShell**:\n```powershell\nirm https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/install.ps1 | iex\n```\n\n**Windows CMD**:\n```cmd\npowershell -ExecutionPolicy Bypass -Command \"irm https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/install.ps1 | iex\"\n```\n\nThis installer:\n1. Cleanly re-installs the plugin (`agy plugin uninstall` + `agy plugin install`).\n2. Downloads the HUD runtime to `~/.gemini/antigravity-cli/agy-hud-runtime/`.\n3. Writes `statusLine.command` into `~/.gemini/antigravity-cli/settings.json`.\n\nOpen a fresh `agy` session — the HUD appears at the bottom of the terminal.\n\n**Idempotent** — re-run the same command anytime to repair drift, upgrade, or clean stale files left by older versions.\n\n### Why not a-single `agy plugin install`?\n\n`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.\n\n### For forks / mirrors\n\n**macOS / Linux**:\n```bash\nAGY_HUD_REPO_RAW=https://raw.githubusercontent.com/your-fork/agy-hud/main \\\nAGY_HUD_REPO_URL=https://github.com/your-fork/agy-hud.git \\\n  bash <(curl -fsSL \"$AGY_HUD_REPO_RAW/scripts/install.sh\")\n```\n\n**Windows PowerShell**:\n```powershell\n$env:AGY_HUD_REPO_RAW = 'https://raw.githubusercontent.com/your-fork/agy-hud/main'\n$env:AGY_HUD_REPO_URL = 'https://github.com/your-fork/agy-hud.git'\nirm \"$env:AGY_HUD_REPO_RAW/scripts/install.ps1\" | iex\n```\n\n### Manual / advanced\n\nIf you prefer to run the steps yourself:\n\n**macOS / Linux**:\n```bash\nagy plugin install https://github.com/icebear0828/agy-hud.git\nbash <(curl -fsSL https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/bootstrap.sh)\n```\n\n**Windows PowerShell**:\n```powershell\nagy plugin install https://github.com/icebear0828/agy-hud.git\n$t = Join-Path $env:TEMP \"agy-hud-bootstrap.js\"\nInvoke-WebRequest -Uri https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/bootstrap.js -OutFile $t -UseBasicParsing\nnode $t; Remove-Item $t\n```\n\n**Windows CMD**:\n```cmd\nagy plugin install https://github.com/icebear0828/agy-hud.git\npowershell -Command \"Invoke-WebRequest -Uri https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/bootstrap.js -OutFile %TEMP%\\agy-hud-bootstrap.js -UseBasicParsing\"\nnode %TEMP%\\agy-hud-bootstrap.js\ndel %TEMP%\\agy-hud-bootstrap.js\n```\n\n---\n\n## Verify\n\nAfter bootstrap:\n\n```bash\n# settings.statusLine should point at the runtime\ncat ~/.gemini/antigravity-cli/settings.json | grep statusLine -A2\n\n# Direct HUD invocation should print the HUD status lines\nnode ~/.gemini/antigravity-cli/agy-hud-runtime/runtime/bin/agy-hud.js\n```\n\nIf quota rows show `Antigravity token expired`, refresh your `agy` login. That is **not** a bootstrap failure.\n\nWindows PowerShell:\n\n```powershell\nGet-Content \"$env:USERPROFILE\\.gemini\\antigravity-cli\\settings.json\"\n& \"$env:USERPROFILE\\.gemini\\antigravity-cli\\agy-hud-runtime\\runtime\\bin\\agy-hud.cmd\"\n```\n\n---\n\n## Diagnose\n\n```bash\n# Inspect token + quota cache state\nnode scripts/diagnose-auth.js\n\n# Tail agy's own statusLine runner errors\nls -t ~/.gemini/antigravity-cli/log/cli-*.log | head -1 | xargs tail -50 | grep statusline\n```\n\nThe 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.\n\n---\n\n## Uninstall\n\n**macOS / Linux**:\n```bash\nbash <(curl -fsSL https://raw.githubusercontent.com/icebear0828/agy-hud/main/uninstall.sh)\n```\n\n**Windows PowerShell**:\n```powershell\nirm https://raw.githubusercontent.com/icebear0828/agy-hud/main/uninstall.ps1 | iex\n```\n\n**Windows CMD**:\n```cmd\npowershell -ExecutionPolicy Bypass -Command \"irm https://raw.githubusercontent.com/icebear0828/agy-hud/main/uninstall.ps1 | iex\"\n```\n\nOr, if you have the repo cloned: `bash uninstall.sh` / `.\\uninstall.ps1`.\n\nThis:\n1. Clears `settings.json` `statusLine` (with `.bak` of the original).\n2. Removes `~/.gemini/antigravity-cli/agy-hud-runtime/`.\n3. Removes the staged plugin (`agy plugin uninstall agy-hud`).\n4. Cleans payload, error log, tmp token mirror, and quota cache files across all roots and tmp directories.\n\n---\n\n## Configuration\n\nOptional. 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:\n\n```json\n{\n  \"theme\": {\n    \"primary\": \"green\",\n    \"secondary\": \"gray\",\n    \"warning\": \"yellow\",\n    \"critical\": \"red\"\n  },\n  \"display\": {\n    \"quotaStyle\": \"table\",\n    \"showTokenBar\": true,\n    \"showBreadcrumbs\": true,\n    \"showGitBranch\": true,\n    \"showCurrentDir\": true,\n    \"showUsername\": false,\n    \"username\": \"\",\n    \"breadcrumbCount\": 3,\n    \"useNerdFonts\": false,\n    \"columnWidth\": 40\n  },\n  \"thresholds\": {\n    \"warning\": 0.7,\n    \"critical\": 0.9\n  },\n  \"language\": \"auto\"\n}\n```\n\n### Configuration fields\n- **`theme`**: Map of HUD component colors (`primary`, `secondary`, `warning`, `critical`). Supports standard terminal colors (`green`, `gray`, `yellow`, `red`, `blue`, `magenta`, `cyan`).\n- **`display`**:\n  - `quotaStyle`: `\"table\"` (default multi-column layout) or `\"compact\"` (inline quota + provider grouped mini bars).\n  - `showTokenBar`: Whether to display the token bar.\n  - `showBreadcrumbs`: Whether to display workspace file breadcrumbs.\n  - `showGitBranch`: Whether to display the current Git branch.\n  - `showCurrentDir`: Whether to display the base name of the current working directory.\n  - `showUsername`: Whether to display the username/email at the start of the HUD statusline.\n  - `username`: A custom string to override the resolved OS or login username/email.\n  - `breadcrumbCount`: Number of files to show in breadcrumbs.\n  - `useNerdFonts`: Set to `true` to use premium developer icons from [Nerd Fonts](https://www.nerdfonts.com/).\n  - `columnWidth`: Max column width for the quota table layout (defaults to `40`).\n- **`thresholds`**: Threshold values (`0.0` to `1.0`) for displaying quota warning and critical usage colors.\n- **`language`**: Lang preference (`\"auto\"`, `\"en\"`, `\"zh\"`).\n\n---\n\n## File structure\n\n```\nagy-hud/\n├── plugin.json                # {\"name\":\"agy-hud\"} — agy plugin marker\n├── gemini-extension.json      # required by agy's remote-install validator\n├── runtime/                   # downloaded by bootstrap to ~/.gemini/.../agy-hud-runtime/runtime/\n│   ├── bin/agy-hud.js         # statusLine entry (stdin JSON → ANSI HUD)\n│   ├── config-wizard.js       # configuration wizard (--config)\n│   ├── config.js              # config loader & writer\n│   ├── encoding.js            # console encoding & Unicode detector\n│   ├── parser.js              # scans workspace metadata & session transcript\n│   ├── paths.js               # cross-platform path resolution helpers\n│   ├── quota.js               # SWR quota orchestrator\n│   ├── quota/                 # quota & auth submodules (PR #62)\n│   │   ├── cache.js           # atomic JSON caching (v3 schema)\n│   │   ├── cloud.js           # API HTTP clients ( OIDC userinfo auth email)\n│   │   ├── models.js          # quota normalizer & window merging\n│   │   └── token.js           # cross-platform OAuth token discovery\n│   ├── renderer.js            # HUD layout orchestrator\n│   ├── renderer/              # ANSI rendering submodules (PR #58)\n│   │   ├── format.js          # colors, abbreviator, duration formatting\n│   │   ├── lang.js            # internationalization (zh/en auto-detection)\n│   │   └── quota-render.js    # column bars & single-row columns (PR #61)\n│   ├── statusline-installer.js# writes settings.json statusLine settings\n│   ├── uninstall.js           # cleans and purges runtime files\n│   └── update-checker.js      # checks for new GitHub releases\n├── scripts/\n│   ├── install.sh             # one-command installer — macOS/Linux\n│   ├── install.ps1            # one-command installer — Windows PowerShell\n│   ├── bootstrap.sh           # repair-only entry (called by install.sh)\n│   ├── bootstrap.js           # actual download + configure logic\n│   ├── configure-utf8.ps1     # optional Windows UTF-8 profile + Git encoding helper\n│   ├── verify-display.js      # E2E: install + bootstrap + PTY-spawn agy + assert HUD\n│   └── diagnose-auth.js\n├── tests/unit/                # modular unit tests (node --test)\n├── .github/workflows/e2e.yml  # cross-platform CI matrix\n└── release.sh                 # npm test → E2E gate → zip → gh release\n```\n\n---\n\n## Cross-platform notes\n\n**Windows UTF-8 helper**: If your terminal is on a non-UTF-8 codepage and you want Unicode bars/borders by default, run:\n\n```powershell\nirm https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/configure-utf8.ps1 | iex\n```\n\nThis 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.\n\n**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.\n\n**File token fallback paths** (searched in order):\n- `~/.gemini/antigravity-cli/antigravity-oauth-token`\n- `$XDG_DATA_HOME/antigravity-cli/antigravity-oauth-token`\n- `$APPDATA/antigravity-cli/antigravity-oauth-token`\n- `$LOCALAPPDATA/antigravity-cli/antigravity-oauth-token`\n\n---\n\n## Verified by CI\n\nEvery push to `main` runs [.github/workflows/e2e.yml](./.github/workflows/e2e.yml) against a 3-OS matrix:\n\n| OS | install.sh runs | bootstrap writes settings.json | HUD command renders status lines |\n|----|------|------|------|\n| ubuntu-latest | ✅ | ✅ | ✅ |\n| macos-latest  | ✅ | ✅ | ✅ |\n| windows-latest | ✅ | ✅ | ✅ |\n\nEach run uploads (14-day retention):\n\n| Artifact | Per-OS | Contents |\n|---|---|---|\n| `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) |\n| `hud-screenshot-<os>` | ubuntu + macos | `hud-ascii-<os>.png` + `hud-unicode-<os>.png` rendered via [charm.sh `freeze`](https://github.com/charmbracelet/freeze). PNG visual evidence — download and open. |\n\nCI 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.\n\n---\n\n## Known issues\n\n- **Windows PNG screenshot**: every CI run uploads `hud-ascii-*.png` and `hud-unicode-*.png` for macOS + Linux via [charm.sh `freeze`](https://github.com/charmbracelet/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).\n\n> **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.\n>\n> 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.\n>\n> **How to enable beautiful Unicode progress bars and borders on Windows:**\n> 1. **PowerShell helper (Recommended)**: Run `irm https://raw.githubusercontent.com/icebear0828/agy-hud/main/scripts/configure-utf8.ps1 | iex`, then restart PowerShell.\n> 2. **Per Session**: Run `chcp 65001` once in your Command Prompt / PowerShell window before opening `agy`.\n> 3. **System-wide UTF-8 (Permanent)**:\n>    - Go to Windows Settings -> **Time & language** -> **Language & region** -> **Administrative language settings**.\n>    - Click **Change system locale**.\n>    - Check **\"Beta: Use Unicode UTF-8 for worldwide language support\"** and restart your computer.\n>    - This forces all terminal sessions to use UTF-8 (`cp65001`) natively.\n\n---\n\n## License\n\nMIT\n",
  "bytes": 15243,
  "sha": "f6a084327a307c7096059dd99c610568624e5c2ff7427abd420c108268f22fd4",
  "repo_slug": "icebear0828/agy-hud",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_icebear0828_agy_hud_ad4fcd4b/readme"
}