Antigravity Token Monitor

Monitor Antigravity session token usage and review session activity in a dashboard.

Antigravity Token Monitor is a VS Code extension that automatically collects, analyzes, and visualizes token usage across your Antigravity coding sessions. It connects to the running Antigravity process via internal RPC, exports token metadata as local JSONL artifacts, and presents the data through a rich Svelte-powered dashboard and a persistent status bar indicator.

---

Features

• 🔥 Real-time Token Tracking — Automatically monitors token usage across all Antigravity sessions
• 🕰️ Historical Session Recovery — Recovers session data that existed before the extension was started by directly querying the RPC server for sessions missing from the active list
• 📊 Interactive Dashboard — Svelte-based webview with KPI cards, heatmaps, model usage tables, and session leaderboards
• 📌 Sidebar Overview — Activity Bar에 상주하는 미니 대시보드 (KPI, 토큰 브레이크다운, 모델 사용량, 30일 히트맵, 세션 리스트)
• 💰 Cost Estimation — Per-model cost calculation using LiteLLM open-source pricing data
• 🏷️ Model Breakdown — Per-model token breakdown (input, output, cache read/write, reasoning) with automatic resolution of internal model placeholder IDs
• 📈 Activity Heatmap — 180-day activity visualization showing daily token usage and cost patterns
• 🔄 RPC Export — Periodically exports session data from the Antigravity RPC server into local JSONL artifacts
• 🔒 Multi-instance Safety — File-based locking prevents duplicate refresh/export across multiple VS Code windows
• ⏱️ Refresh Countdown — Visual countdown timer with circular progress ring showing time until the next auto-refresh
• 🖥️ Status Bar — Always-visible total token count in the VS Code status bar

---

⚠️ Disclaimer

Warning

• This is an unofficial, community-driven project and is not affiliated with or endorsed by Google.
• The extension relies on undocumented internal RPC endpoints of the Antigravity process. These may change or break without notice in any Antigravity update.
• Token counts labeled as "estimated" are heuristic approximations (text length ÷ 4) and may differ significantly from actual usage.
• Cost estimates are based on LiteLLM's open-source pricing data and may not reflect your actual billing. Do not use these values for financial decisions.
• The extension makes local HTTPS requests to 127.0.0.1 to communicate with the Antigravity process. No data is sent to external servers (except fetching the LiteLLM pricing JSON from GitHub).
• When exportStepsJsonl is enabled, conversation content that Antigravity normally stores encrypted will be exported as plain-text JSONL and cached on your local machine (~/.gemini/antigravity/.token-monitor/). Be aware that this may expose sensitive conversation data in an unencrypted form.

---

Getting Started

Prerequisites

• VS Code ≥ 1.96.0
• Node.js ≥ 18
• A running Antigravity instance (the extension auto-detects the process)

Installation (Development)

# Clone the repository
git clone https://github.com/user/antigravity-token-monitor.git
cd antigravity-token-monitor

# Install dependencies
npm install

# Compile the extension
npm run compile

# Or watch for changes during development
npm run watch

Then press F5 in VS Code to launch the Extension Development Host.

Usage

1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run Antigravity Token Monitor: Open Dashboard
3. The dashboard opens in a webview panel, displaying token usage data

You can also click the token counter in the status bar to open the dashboard.

Sidebar: Activity Bar의 그래프 아이콘을 클릭하면 사이드바에 토큰 사용량 요약이 항상 표시됩니다.

---

Commands

Command	Description
Antigravity Token Monitor: Open Dashboard	Open the token monitoring dashboard
Antigravity Token Monitor: Refresh Now	Trigger an immediate data refresh
Antigravity Token Monitor: Export Sessions Now	Force-export all sessions and display the count
Antigravity Token Monitor: Reset Cache	Delete all cached data and re-process from scratch

---

Configuration

All settings are under antigravity-token-monitor.* in VS Code settings.

Setting	Default	Description
sessionRoot	~/.gemini/antigravity	Override the Antigravity session root directory
pollIntervalMs	60000	How often the extension rescans sessions (ms)
historyLimit	120	Max snapshots to keep per session
MS:	maxFileBytes	10485760 (10MB)
WR:	useRpcExport	true
BS:	exportStepsJsonl	false
NR:	rpcExportIntervalMs	300000
SK:	rpcTimeoutMs	5000

Troubleshooting

See docs/ISSUES.md for known issues and solutions.

---

Architecture

The extension follows a layered pipeline architecture:

Data Acquisition → Analysis → Orchestration → Presentation

Data Acquisition: The ProcessLocator detects the running Antigravity language_server process, the AntigravityRpcClient fetches token metadata via HTTPS RPC, and the TrajectoryExporter serializes it into local usage.jsonl files. Sessions not found in the active RPC list are recovered via direct fallback queries, enabling historical session data collection even for sessions that existed before the extension was started. The modelAliases module resolves internal model placeholder IDs (MODEL_PLACEHOLDER_*) to human-readable names.

Analysis: The SessionScanner enumerates session directories, the AntigravitySessionParser extracts token counts (either from structured usage records or text-based estimation), and the LiteLlmPricingCatalog calculates per-model costs.

Orchestration: The TokenMonitorService coordinates periodic polling, RPC exports, and event emission with debounced updates. A file-based PollLock mechanism prevents duplicate processing when multiple VS Code instances are running.

Presentation: The TokenStatusBar shows a persistent token count, the DashboardPanel renders a Svelte webview with 13 UI components including KPI strips, heatmaps, model tables, session leaderboards, and a real-time refresh countdown timer, and the SidebarViewProvider renders a compact WebviewView in the Activity Bar with 6 sidebar-optimized components (KPI, token mix, model usage, mini heatmap, session list, sync status).

For a detailed breakdown, see docs/architecture.md in this repository.

---

Project Structure

src/
├── extension.ts               # Extension entry point
├── config.ts                  # Configuration reader
├── types.ts                   # Shared type definitions
├── modelAliases.ts            # Model placeholder ID → name resolution
├── rpc/                       # Data acquisition (RPC layer)
├── monitor/                   # Scanning, analysis, orchestration
│   └── pollLock.ts            #   File-based lock for multi-instance safety
├── parser/                    # Token parsing (reported/estimated)
├── pricing/                   # LiteLLM-based cost estimation
├── storage/                   # Persistence (artifacts + snapshots)
├── statusBar/                 # VS Code status bar
└── webview/                   # Svelte UI
    ├── components/            #   13 dashboard components
    ├── sidebar/               #   Sidebar mini-dashboard
    │   ├── components/        #     6 sidebar-optimized components
    │   ├── SidebarApp.svelte  #     Sidebar root
    │   ├── main.ts            #     Sidebar entry point
    │   └── sidebarApi.ts      #     Sidebar ↔ extension messaging
    ├── sidebarViewProvider.ts #   WebviewViewProvider for Activity Bar
    ├── getSidebarHtml.ts      #   Sidebar HTML shell
    └── lib/                   #   Shared stores, formatters, utilities

---

Development

# Compile
npm run compile

# Watch mode
npm run watch

# Type check (extension)
npm run typecheck

# Type check (webview)
npm run typecheck:webview

# Run webview tests
npm run test:webview

Tech Stack

Layer	Technology
Extension	TypeScript, Node.js
Webview UI	Svelte 5
Bundler	esbuild + esbuild-svelte
Testing	Vitest, Testing Library

---

How It Works

1. Process Detection — Finds the Antigravity language_server process via ps and extracts its CSRF token and port
2. RPC Communication — Calls GetCascadeTrajectoryGeneratorMetadata to fetch per-session token usage metadata
3. Historical Recovery — Sessions missing from the active RPC list are queried directly using file-system session IDs as a fallback, recovering data from sessions that existed before the extension was started
4. Model Resolution — Internal model placeholder IDs (MODEL_PLACEHOLDER_*) are resolved to human-readable names via a static mapping, with responseModel fields taking priority when available
5. JSONL Serialization — Normalizes metadata into usage.jsonl records stored under .token-monitor/rpc-cache/
6. Token Parsing — Extracts model-specific token breakdowns (input, output, cache, reasoning) from structured records, or estimates from text length as fallback
7. Cost Calculation — Matches models against LiteLLM's open-source pricing catalog to compute USD costs
8. Visualization — Renders data in the status bar, a sidebar mini-dashboard (Activity Bar), and a full Svelte webview dashboard with a real-time refresh countdown

---

Inspired By

• antigravity-storage-manager — Session token parsing approach
• tokscale — Token usage tracking and visualization

---

License

This project is licensed under the MIT License.