agy-token-monitor
Provides real-time telemetry for Google Antigravity by connecting to the local language server's loopback RPC, exposing dual-window quota pools (5-hour rolling and weekly limits) per model family, reset countdowns, account plan and available credits, plus active conversation token consumption read from local transcript files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agy-token-monitor check my remaining Antigravity quota before the next tool call"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
agy-token-monitor ⚡
Self-aware dual-window quota telemetry and session token monitor for Google Antigravity.
Runs as both a native Model Context Protocol (MCP) server for AI coding assistants and a standalone terminal CLI.
💡 Why This Exists
Autonomous coding agents can rapidly burn thousands of tokens through iterative tool loops, subagent fan-outs, and large file diffs. When an agent hits an unannounced rate limit (HTTP 429 / quota exhaustion):
Generations are terminated mid-stream, leaving half-written files and broken AST syntax.
The agent is blocked from even sending an error message or explaining what is left to do.
Repositories are left in uncommitted, dirty states.
agy-token-monitor gives Antigravity agents continuous self-awareness of their exact remaining headroom across both 5-hour rolling demand limits and weekly tier entitlement limits, enabling graceful checkpointing before hitting hard boundaries.
Related MCP server: headroom
🏗️ Architecture
┌────────────────────────────────────────────────────────┐
│ Antigravity Background Sidecar │
│ (language_server binary) │
│ │
│ • Dynamically allocated loopback port (127.0.0.1) │
│ • Ephemeral --csrf_token in process arguments │
└───────────────────────────┬────────────────────────────┘
│ Connect RPC (POST / JSON)
│ • RetrieveUserQuotaSummary
│ • GetUserStatus
▼
┌────────────────────────────────────────────────────────┐
│ agy-token-monitor │
│ (0 LLM tokens burned · ~15ms latency) │
│ │
│ • Auto-discovers PID, CSRF token, and active port │
│ • Parses 5h rolling & weekly dual-window pools │
│ • Scans session transcript.jsonl for token bloat │
└───────────────────────────┬────────────────────────────┘
│
┌─────────────┴─────────────┐
▼ ▼
[MCP stdio JSON-RPC] [Standalone CLI]
(For AI Agent Turns) (python server.py --check)Zero LLM Token Cost: Connects directly to the local language server's loopback RPC. Telemetry checks cost 0 API tokens.
Zero Pip Dependencies: Built entirely with the Python standard library (
subprocess,urllib.request,ssl,json,re).Cross-Platform: Works on Windows (PowerShell/netstat), macOS (ps/lsof), and Linux (ps/ss).
🚀 Quickstart
1. Clone & Standalone CLI Usage
Clone the repository:
git clone https://github.com/NaxonM/agy-token-monitor.git
cd agy-token-monitor🤖 One-Prompt Setup via Agent: You can point your AI coding assistant directly at
AGENTS.md("Configure agy-token-monitor according to AGENTS.md"), and it will automatically register the MCP server in yourmcp_config.jsonand install the companion skill for you.
Verify your active Antigravity quota straight from your terminal (zero pip dependencies required):
# Print formatted real-time dashboard
python server.py --check
# Print raw JSON telemetry
python server.py --json
# Print active conversation token consumption
python server.py --session(Optional) Install into your Python environment for a direct agy-token-monitor CLI command:
pip install -e .
# Now callable from any directory
agy-token-monitor --checkTerminal Output Preview:
### [Antigravity Dual-Window Token & Quota Self-Awareness]
- **Working Account:** `developer@gmail.com` (Google AI Pro)
- **Credits Available:** Prompt: `500` | Flow: `100`
- **Status Verdict:** Gemini weekly pool is HEALTHY (46.3%) | Claude/GPT weekly limit is EXHAUSTED (0% left)
#### Dual-Window Quota Pools (Rolling 5h & Weekly):
**Gemini Models:**
- Weekly Limit Remaining (weekly): 46.3% [HEALTHY] (resets in 10h 55m)
- Five Hour Limit Remaining (5h): 100% [HEALTHY] (resets in 4h 56m)
**Claude and GPT models:**
- Weekly Limit Remaining (weekly): 0% [EXHAUSTED] (resets in 5d 1h)
- Five Hour Limit Remaining (5h): 100% [DISABLED] (resets in 4h 56m)
#### Current Conversation Context Pressure:
- **Conversation ID:** `0205c6c6-8e40-473b-a238-bb9d711295a4`
- **Steps Recorded:** 17
- **Estimated Session Tokens:** ~4,733 tokens
- **Context Status:** HEALTHY (Plenty of context room)
- **Breakdown:** User: ~226 | Agent: ~363 | Tools: ~262 | Thinking: ~2762. Antigravity MCP Server Setup
Add agy-token-monitor to your global Antigravity config (~/.gemini/config/mcp_config.json):
Option A: Direct Python Script
{
"mcpServers": {
"agy-token-monitor": {
"command": "python",
"args": [
"<path-to-repo>/server.py"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}Note: Replace
<path-to-repo>with the absolute path to where you cloned this repository (e.g.C:/path/to/agy-token-monitor/server.pyon Windows or/home/username/agy-token-monitor/server.pyon macOS/Linux).
Option B: Installed CLI Command (pip install -e .)
{
"mcpServers": {
"agy-token-monitor": {
"command": "agy-token-monitor",
"args": [
"--mcp"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}🛠️ MCP Tools Exposed
Tool Name | Parameters | Description |
| None | Returns real-time dual-window 5h and weekly quotas, per-model pool fractions, reset timers, and Google account plan credits. |
|
| Reads active |
|
| Returns a consolidated Markdown executive dashboard combining dual-window quotas and conversation token consumption. |
🧠 Companion Skill (token-awareness)
This repository bundles an agent skill in skill/token-awareness/SKILL.md that teaches Antigravity agents how to govern tokens autonomously:
The 3% Landing Reserve: The final 3% of quota is locked exclusively for clean file closing, syntax validation, and committing state. Generative tasks never burn quota down to 0%.
Heartbeat & Runway Protocol: During multi-file or multi-step tasks, the agent probes
get_account_quota()every 3–5 tool steps. If remaining runway is insufficient for the next milestone, it halts cleanly, commits progress, and states the exact countdown until quota refresh.Quota-Scaled Ambiguity Gates: When quota drops below 10%, guesswork is forbidden. The agent must halt for user clarification with bounded
[A]vs[B]choices before executing high-burn operations.Swarm Governance: Coordinators running weekly-quota models explicitly assign subagents to
Model: 'flash_lite'or'flash'to spare the weekly entitlement tier.
Installing the Skill
Copy the bundled skill into your global Antigravity skills directory:
# Windows PowerShell
Copy-Item -Recurse "skill/token-awareness" "$env:USERPROFILE\.gemini\config\skills\"
# macOS / Linux
cp -r skill/token-awareness ~/.gemini/config/skills/🔍 How It Works Under The Hood
Antigravity executes a background binary (language_server.exe on Windows, language_server_macos on Apple Silicon, or language_server on Linux) with command-line arguments:
language_server.exe --csrf_token e4a891f8-... --https_server_port 0 ...Dynamic Port Discovery: Because
--https_server_port 0assigns an ephemeral OS port,agy-token-monitorinspects the local socket table (netstaton Windows,lsof/sson Unix) matching the language server PID.Dynamic CSRF Authentication: The script extracts the security token directly from the process command line.
Connect RPC Telemetry: Issues local requests to:
POST /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummaryPOST /exa.language_server_pb.LanguageServerService/GetUserStatus
Zero-Latency In-Memory Caching: Successful connection parameters (PID, port, token) are cached in-memory with a 30-second TTL.
📄 License
MIT License. See LICENSE for details.
Available Tools
3 toolsget_account_quotaA
Fetch real-time dual-window quota (5h rolling & weekly limits) for Gemini and Claude/GPT pools directly from Antigravity language server.
Inputs: no named parameters.
get_session_token_usageC
Calculate token consumption and context bloat across the current conversation transcript.
Inputs: conversation_id.
get_token_awareness_summaryA
Get a unified executive summary combining dual-window quota health (5h & weekly) and current conversation token consumption.
Inputs: conversation_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools have reasonably clear boundaries: quota (account-level), session usage (conversation-level), and a summary that aggregates both. The summary tool overlaps by design with the other two, which could tempt an agent to skip the granular tools, but the descriptions make the distinction explicit.
All three tools follow the same verb_noun snake_case pattern with a consistent 'get_' prefix (get_account_quota, get_session_token_usage, get_token_awareness_summary). The names are predictable and immediately map to their outputs.
Three tools is on the lean side but appropriate for a narrowly scoped monitoring server covering two distinct metrics plus an aggregate. Nothing feels superfluous, though the summary tool is arguably a convenience layer rather than an independent capability.
The core read path (quota, session consumption, combined health) is covered, but a monitoring domain typically also implies historical trends, threshold/alert configuration, or reset-time details, none of which exist here. It is read-only with no lifecycle operations, which is acceptable for a monitor but leaves notable gaps.
Related MCP Connectors
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
Analytics for MCP servers. Find out which of your tools agents get wrong. MCPulse shows you which tools AI agents retry, which come back empty, and which they never call at all. Two lines inside your own server. It never sees your arguments or your results. getmcpulse.com
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Token Budget MCP — hard per-session token + spend cap with signed budget-exhausted
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server that reduces token consumption in AI coding assistants by up to 90% via structural reads, PreToolUse hooks, and tp-\* subagents.25481 npm5MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that provides real-time rate-limit and context budget awareness to Claude Code, enabling it to plan tasks that fit within its constraints and defer work when needed.8 npmApache 2.0
- AlicenseAqualityCmaintenanceAn MCP server that exposes Claude Code's real-time rate limit usage so that an orchestrator can check remaining capacity before launching subtasks.17 npmMIT
- AlicenseAqualityBmaintenanceAn MCP server that acts as a context-aware code retrieval broker for AI coding agents, enforcing backpressure and token budgeting to prevent context window overflow.443 npmMIT