{"id":50659134,"url":"https://github.com/savvy773/ai_usage","last_synced_at":"2026-06-08T01:07:40.688Z","repository":{"id":362845763,"uuid":"1250237358","full_name":"savvy773/ai_usage","owner":"savvy773","description":"Monitor Claude, Codex, and Gemini CLI usage in one local dashboard. No cloud. No telemetry.","archived":false,"fork":false,"pushed_at":"2026-06-06T06:52:17.000Z","size":696,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T08:12:58.991Z","etag":null,"topics":["claude","cli-tools","codex","dashboard","gemini","node-pty","powershell","sveltekit","typescript"],"latest_commit_sha":null,"homepage":"https://savvy773.github.io/ai_usage/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/savvy773.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T12:41:48.000Z","updated_at":"2026-06-06T06:52:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/savvy773/ai_usage","commit_stats":null,"previous_names":["savvy773/ai_usage"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/savvy773/ai_usage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savvy773%2Fai_usage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savvy773%2Fai_usage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savvy773%2Fai_usage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savvy773%2Fai_usage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/savvy773","download_url":"https://codeload.github.com/savvy773/ai_usage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savvy773%2Fai_usage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34043832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","cli-tools","codex","dashboard","gemini","node-pty","powershell","sveltekit","typescript"],"created_at":"2026-06-08T01:07:40.221Z","updated_at":"2026-06-08T01:07:40.679Z","avatar_url":"https://github.com/savvy773.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cbr /\u003e\n  \u003cimg src=\"docs/ai_dash.png\" alt=\"AI Usage Dashboard\" width=\"860\" style=\"border-radius:14px\" /\u003e\n  \u003cbr /\u003e\u003cbr /\u003e\n\n  \u003ch1\u003eAI Usage Dashboard\u003c/h1\u003e\n  \u003cp\u003eMonitor \u003cstrong\u003eClaude\u003c/strong\u003e, \u003cstrong\u003eCodex\u003c/strong\u003e, and \u003cstrong\u003eAntigravity CLI\u003c/strong\u003e usage in one local dashboard.\u003cbr /\u003eNo cloud. No telemetry. Runs entirely on your machine.\u003c/p\u003e\n\n  \u003cbr /\u003e\n\n  \u003ca href=\"https://savvy773.github.io/ai_usage/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/%F0%9F%8C%90%20Landing%20Page-6d5bff?style=for-the-badge\" alt=\"Landing Page\" /\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://github.com/savvy773/ai_usage/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/savvy773/ai_usage?style=for-the-badge\u0026color=a855f7\u0026label=Release\" alt=\"Release\" /\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://github.com/savvy773/ai_usage/wiki\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Wiki-1e293b?style=for-the-badge\u0026logo=gitbook\u0026logoColor=white\" alt=\"Wiki\" /\u003e\n  \u003c/a\u003e\n\n\u003cbr /\u003e\u003cbr /\u003e\n\n  \u003cimg src=\"https://img.shields.io/badge/SvelteKit-FF3E00?style=flat-square\u0026logo=svelte\u0026logoColor=white\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tailwind_v4-38BDF8?style=flat-square\u0026logo=tailwindcss\u0026logoColor=white\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node--pty-22d3ee?style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-a855f7?style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Windows-only-0078D4?style=flat-square\u0026logo=windows\u0026logoColor=white\" /\u003e\n\n\u003cbr /\u003e\u003cbr /\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"#-install\"\u003eInstall\u003c/a\u003e ·\n    \u003ca href=\"#-features\"\u003eFeatures\u003c/a\u003e ·\n    \u003ca href=\"#-cli-targets\"\u003eCLI Targets\u003c/a\u003e ·\n    \u003ca href=\"#-development\"\u003eDevelopment\u003c/a\u003e ·\n    \u003ca href=\"docs/architecture.md\"\u003eArchitecture\u003c/a\u003e ·\n    \u003ca href=\"docs/fix_check.md\"\u003eFix Checklist\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cbr /\u003e\n\u003c/div\u003e\n\n---\n\nA **SvelteKit server** spawns each CLI in a virtual terminal via **node-pty**, captures the output, parses usage data, and stores results locally. Manual refreshes and foreground auto-refreshes can collect live data; background or stale-page auto-refreshes return cached data so no hidden CLI window steals focus. The browser renders from cached JSON on first paint — no API keys, no accounts, no data leaving your machine.\n\n\u003cbr /\u003e\n\n## 🗺 Setup Flow\n\n```mermaid\nflowchart LR\n    A[\"① Install CLIs\\nclaude-code \u0026 codex\\n(and Antigravity CLI)\"] --\u003e B[\"② Authenticate\\ncd %USERPROFILE%\\nclaude → codex → agy\\n(complete login once)\"]\n    B --\u003e C[\"③ Install Dashboard\\nirm …/install.ps1 | iex\\n(auto-installs git, node, pnpm)\"]\n    C --\u003e D[\"④ View Usage\\nstart-server.ps1 -Open\\n→ 127.0.0.1:5173\"]\n\n    style A fill:#1e1b4b,stroke:#6d5bff,color:#c4b5fd\n    style B fill:#1c1410,stroke:#fb923c,color:#fdba74\n    style C fill:#1a0f2e,stroke:#a855f7,color:#d8b4fe\n    style D fill:#052e16,stroke:#22c55e,color:#86efac\n```\n\n\u003cbr /\u003e\n\n## ✨ Features\n\n|     | Feature              | Description                                                                                 |\n| :-: | :------------------- | :------------------------------------------------------------------------------------------ |\n| ⚡  | **Multi-provider**   | Runs Claude `/usage` · Codex `/status` · Antigravity `/usage` in virtual terminals          |\n| ⏱️  | **Auto interval**    | Choose 1, 3, 5, or 10 minutes; 5 minutes is the default                                     |\n|  ↻  | **Smart retry**      | Up to 5 attempts with phase diagnostics and repeated slash-command confirmation             |\n| 📊  | **Weekly Pace card** | Usage bar vs. 20 % minimum threshold — see if you're on track                               |\n|  ⏱  | **Reset countdown**  | Live per-provider countdown to next usage reset                                             |\n| 📡  | **Live server logs** | SSE stream rendered directly in the browser — no polling                                    |\n| 💾  | **Dual cache**       | Server-side JSON history (10-min buckets) + `localStorage` fallback for instant first paint |\n\n\u003cbr /\u003e\n\n## 📦 Install\n\n### Step 1 — Install the AI CLIs\n\nThe dashboard collects data by running each CLI in a virtual terminal. **Install whichever CLIs you want to monitor:**\n\n```powershell\nirm https://claude.ai/install.ps1 | iex    # Claude\nnpm install -g @openai/codex               # Codex\nirm https://antigravity.google/cli/install.ps1 | iex  # Antigravity\n```\n\n### Step 2 — Pre-authenticate each CLI\n\n\u003e **This step is required.** Manual refresh and foreground auto-refresh launch CLIs silently and send a slash command — any first-run wizard, login prompt, or trust dialog will cause a timeout and no data will be collected.\n\nRun each CLI **once** in the directory you plan to use as your working directory, complete the full auth flow, then exit:\n\n```powershell\ncd %USERPROFILE%\n\nclaude               # → OAuth → /exit\ncodex                # → setup → exit\nagy                  # → setup → exit\n```\n\n\u003e If you want CLIs to run in a different directory, set `AI_USAGE_CWD` in `.env` — but you must authenticate there too. See [Custom CLI working directory](#) below.\n\n### Step 3 — Install the Dashboard\n\n**One-liner** — checks prerequisites, auto-installs git/Node.js/pnpm if missing:\n\n```powershell\n# Interactive (prompts for confirmation)\nirm https://raw.githubusercontent.com/savvy773/ai_usage/main/scripts/install.ps1 | iex\n\n# Unattended — skip all prompts, open browser on finish\n\u0026 ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/savvy773/ai_usage/main/scripts/install.ps1'))) -Yes -Open\n```\n\n**Or clone manually:**\n\n```powershell\ngit clone https://github.com/savvy773/ai_usage.git\ncd ai_usage\npnpm install\n.\\scripts\\start-server.ps1 -Open\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eSystem requirements\u003c/summary\u003e\n\n| Requirement                         | Why                                                      |\n| :---------------------------------- | :------------------------------------------------------- |\n| Windows                             | `node-pty` and the server launcher are Windows-only      |\n| Node.js 20+                         | Runtime — auto-installed by one-liner if missing         |\n| pnpm                                | Package manager — auto-installed by one-liner if missing |\n| **Visual Studio Build Tools (C++)** | `node-pty` compiles native code during `pnpm install`    |\n| Python 3                            | Used by `node-gyp` during native compilation             |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild Tools missing? — fix for fresh PCs\u003c/summary\u003e\n\n```powershell\nwinget install Microsoft.VisualStudio.2022.BuildTools `\n  --override \"--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --passive\"\n```\n\nThen re-run `pnpm install`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003estart-server.ps1 options\u003c/summary\u003e\n\n```powershell\n.\\scripts\\start-server.ps1 -Open          # open browser on start\n.\\scripts\\start-server.ps1 -Port 5174     # custom port (default 5173)\n.\\scripts\\start-server.ps1 -Mode dev      # hot-reload dev mode\n.\\scripts\\start-server.ps1 -Mode preview  # production preview (default)\n.\\scripts\\start-server.ps1 -NoRestart     # skip server restart\n.\\scripts\\start-server.ps1 -Status        # show running server info\n.\\scripts\\start-server.ps1 -Help          # all options\n```\n\n\u003e Uses `--strictPort`. Only stops a server it previously started — never kills unrelated processes on the same port.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCustom CLI working directory\u003c/summary\u003e\n\nThe normal setup is two shared candidates in `.env`:\n\n```text\nAI_USAGE_CWD=D:\\Code\\_temp\nAI_USAGE_CWD_CANDIDATES=%TEMP%\n```\n\nWhen `AI_USAGE_CWD` or `AI_USAGE_CWD_CANDIDATES` is set, the collector uses only those shared candidates, up to three paths total:\n\n1. `AI_USAGE_CWD`\n2. `AI_USAGE_CWD_CANDIDATES`, split by semicolon\n\nIf both are unset, the built-in fallback order is:\n\n1. `..\\..\\_temp` when installed under `_toolkit\\aI_usage`\n2. `%TEMP%`\n3. `%TMP%`\n\nTo change the preferred path or add fallbacks for multiple PCs, edit `.env`:\n\n```text\nAI_USAGE_CWD=..\\..\\_temp\nAI_USAGE_CWD_CANDIDATES=%TEMP%\n```\n\nRelative paths such as `..\\..\\_temp` are resolved from the dashboard project root, so the same config works across PCs after `irm` installation. Keep this directory outside the Git repo to avoid repo-root trust prompts. `%TEMP%`, `%TMP%`, `$env:TEMP`, and `$env:TMP` are expanded at runtime. The collector creates the working directory if it is missing, but it does not intentionally create persistent files inside it; if a CLI creates temporary files, it owns their cleanup. Each CLI uses at most three candidates. Shared settings are enough for normal use. To customize an unusual provider-specific setup, set `AI_USAGE_CWD_CLAUDE`, `AI_USAGE_CWD_CODEX`, `AI_USAGE_CWD_GEMINI` (used by Antigravity), or their `AI_USAGE_CWD_CANDIDATES_*` variants. Each CLI must be pre-authenticated/trusted in at least one candidate directory. Parsed raw snapshots include the selected `workingDirectory` and all `workingDirectoryCandidates`. Claude retries incomplete `/usage` loading in the same working directory; it only advances to the next candidate when a trust prompt blocks collection.\n\nCodex stores trusted directories per user in `%USERPROFILE%\\.codex\\config.toml` under `[projects.'path']` entries with `trust_level = \"trusted\"`.\n\n\u003c/details\u003e\n\n\u003cbr /\u003e\n\n## 🔄 Auto Refresh\n\nAuto refresh defaults to **5 minutes**. Use the interval control in the dashboard to choose **1, 3, 5, or 10 minutes**.\n\nOnly an active foreground page starts a live collection. If the tab is hidden, blurred, or stale, the refresh API returns cached data and defers the next check instead of launching provider CLIs. Manual **Refresh** still starts a live collection on demand.\n\n\u003cbr /\u003e\n\n## 🖥 CLI Targets\n\n| Provider        | Command  | Slash     | Shows                          |\n| :-------------- | :------- | :-------- | :----------------------------- |\n| Claude          | `claude` | `/usage`  | current session + weekly usage |\n| Codex           | `codex`  | `/status` | 5h limit + weekly limit        |\n| Antigravity CLI | `agy`    | `/usage`  | per-model usage + resets       |\n\n\u003e Antigravity `/usage` works with plain `agy`; no dashboard-specific skip-permissions flag is required.\n\n\u003cbr /\u003e\n\n## 🔧 Development\n\n```powershell\npnpm dev        # hot-reload dev server\npnpm check      # TypeScript + Svelte type check\npnpm build      # production build\npnpm lint       # ESLint + Prettier\n```\n\nVerbose collector output:\n\n```powershell\n$env:AI_USAGE_DEBUG_LOGS=1; .\\scripts\\start-server.ps1\n```\n\n\u003cbr /\u003e\n\n## 📂 Data Files\n\nAll runtime files are git-ignored.\n\n| Path                                   | Description                                 |\n| :------------------------------------- | :------------------------------------------ |\n| `data/usage-history.json`              | Full history — 10-min buckets, last 12 kept |\n| `data/usage-latest.json`               | Latest payload served by `/api/usage`       |\n| `data/raw/{provider}-latest.txt`       | Last raw CLI terminal output                |\n| `data/raw/{provider}-last-failure.txt` | Last failed capture                         |\n| `data/logs/collector.log`              | Collector diagnostics                       |\n| `data/logs/server.log`                 | Server log                                  |\n\nCodex `codex-loading` captures with no usage markers are treated as startup misses while retries continue. If Codex asks for a `/status` refresh, the collector clears the prompt before resending `/status` in the same session. These captures are still visible in `{provider}-latest.*`, but they do not produce normal recovery noise unless the final attempt fails.\n\n\u003cbr /\u003e\n\n## 🛠 Tech Stack\n\n\u003cp\u003e\n  \u003ca href=\"https://kit.svelte.dev/\"\u003e\u003cimg src=\"https://img.shields.io/badge/SvelteKit_2-FF3E00?style=flat-square\u0026logo=svelte\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://tailwindcss.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Tailwind_v4-38BDF8?style=flat-square\u0026logo=tailwindcss\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.shadcn-svelte.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/shadcn--svelte-18181B?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/microsoft/node-pty\"\u003e\u003cimg src=\"https://img.shields.io/badge/node--pty-22d3ee?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://vitejs.dev/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Vite_8-646CFF?style=flat-square\u0026logo=vite\u0026logoColor=white\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr /\u003e\n\n## 📖 Docs\n\n|                                                   |                                                                |\n| :------------------------------------------------ | :------------------------------------------------------------- |\n| [Architecture](docs/architecture.md)              | Implementation structure, API contract, refresh and cache flow |\n| [Fix Checklist](docs/fix_check.md)                | Step-by-step diagnostics for collection and parser errors      |\n| [Wiki](https://github.com/savvy773/ai_usage/wiki) | Quick Start, API Reference, and more                           |\n\n\u003cbr /\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003csub\u003e© 2026 savvy773 · MIT License · Local. Private. Yours.\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsavvy773%2Fai_usage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsavvy773%2Fai_usage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsavvy773%2Fai_usage/lists"}