Skip to main content
Glama

agy-token-monitor ⚡

License: MIT Python Dependencies MCP Platform

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):

  1. Generations are terminated mid-stream, leaving half-written files and broken AST syntax.

  2. The agent is blocked from even sending an error message or explaining what is left to do.

  3. 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 your mcp_config.json and 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 --check

Terminal 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: ~276

2. 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.py on Windows or /home/username/agy-token-monitor/server.py on 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

get_account_quota

None

Returns real-time dual-window 5h and weekly quotas, per-model pool fractions, reset timers, and Google account plan credits.

get_session_token_usage

conversation_id (optional)

Reads active transcript.jsonl under ~/.gemini/antigravity/brain/<id> and calculates total tokens burned, step breakdown (User, Thinking, Agent, Tool I/O), and context pressure.

get_token_awareness_summary

conversation_id (optional)

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:

  1. 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%.

  2. 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.

  3. 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.

  4. 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 ...
  1. Dynamic Port Discovery: Because --https_server_port 0 assigns an ephemeral OS port, agy-token-monitor inspects the local socket table (netstat on Windows, lsof/ss on Unix) matching the language server PID.

  2. Dynamic CSRF Authentication: The script extracts the security token directly from the process command line.

  3. Connect RPC Telemetry: Issues local requests to:

    • POST /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary

    • POST /exa.language_server_pb.LanguageServerService/GetUserStatus

  4. 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 tools
get_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

    B3.4/5.0

    Scored across 3 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP 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 npm
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      An 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.
      4
      43 npm
      MIT