Skip to main content
Glama
Sign In
agy-token-monitor

agy-token-monitor

by NaxonM
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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.

NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are supplied, so the description carries the full behavioral burden. It usefully discloses that values are real-time, that there are two windows (5h rolling and weekly), and that the source is the Antigravity language server, which implies a read-only, live query. It says nothing about authentication requirements, latency, or what happens if the language server is unavailable, which leaves meaningful gaps for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence with the action front-loaded and no wasted words. Every clause (real-time, dual-window, 5h rolling and weekly, pool coverage, source) adds information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read tool with no annotations and no output schema, the description covers the key facts: what is measured, the two time windows, which pools, and the data source. The main remaining gap is the shape of the returned data, which the description only gestures at since no output schema exists to document it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly implies the tool is unfiltered and returns all pools and windows at once, which is consistent with the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Fetch real-time dual-window quota') and scopes it to the 5h rolling and weekly limits for Gemini and Claude/GPT pools. It is clearly a quota/limits lookup rather than a usage or token-count lookup, which implicitly separates it from the siblings. It does not explicitly name those siblings, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the tool for checking remaining quota against rate limits, and the mention of Gemini/Claude/GPT pools hints at scope. There is no explicit when-to-use, when-not-to-use, or guidance on choosing it over get_session_token_usage or get_token_awareness_summary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_session_token_usageC

Calculate token consumption and context bloat across the current conversation transcript.

NameRequiredDescriptionDefault
conversation_idNoOptional conversation ID to inspect. Defaults to the latest active conversation.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full disclosure burden, and it does not state that this is a read-only computation, whether it costs tokens itself, or what the result looks like. There is no output schema either, yet the description gives no indication of the shape of the 'token consumption' or 'context bloat' figures. It does not contradict anything, but it discloses very little behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no filler or redundancy. It is efficient, though the brevity is partly the source of the missing guidance rather than pure economy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple one-optional-parameter tool, so the definition is minimally adequate. With no output schema and no description of the returned metrics, an agent cannot anticipate what 'context bloat' means numerically or how to interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single optional conversation_id parameter is fully documented in the schema, so the baseline is 3. The description adds no parameter meaning and even skews toward 'current conversation transcript' while the schema allows inspecting an arbitrary conversation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb ('Calculate') and specific metrics ('token consumption and context bloat') scoped to the conversation transcript, so an agent knows exactly what the tool produces. It does not differentiate itself from siblings like get_token_awareness_summary or get_account_quota, leaving overlap ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no exclusions, and no mention of the two sibling tools that plausibly cover adjacent token/quota reporting. The phrase 'current conversation transcript' hints at scope but is never framed as a selection rule versus the alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_token_awareness_summaryA

Get a unified executive summary combining dual-window quota health (5h & weekly) and current conversation token consumption.

NameRequiredDescriptionDefault
conversation_idNoOptional conversation ID. Defaults to active conversation.

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It conveys that the tool is a read-style summary and identifies what is combined, but says nothing about permissions, whether the summary is cached/live, or any rate limits. For a low-risk read this is acceptable, yet it leaves meaningful behavioral questions unanswered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, and the key detail (5h & weekly windows) is packed efficiently. It is dense but not padded; slightly more structure could help but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-optional-parameter summary tool with no output schema, the description is nearly sufficient: it explains what the summary covers and that it combines quota and consumption data. Minor gaps are the relationship to sibling tools and whether results are scoped by conversation by default, which the schema partially covers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single optional conversation_id is already documented as defaulting to the active conversation. The description adds no further meaning about that parameter, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Get') and a clearly defined resource ('unified executive summary'), and spells out what is aggregated: dual-window quota health (5h & weekly) plus current conversation token consumption. It only implicitly distinguishes itself from siblings get_account_quota and get_session_token_usage; an agent can infer it is the combined view but the description never names them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word 'unified' implies this is the aggregate alternative to the two narrower sibling tools, but there is no explicit when-to-use statement, no exclusions, and no guidance on choosing this over get_account_quota or get_session_token_usage. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.2.0
    • First observedget_account_quota
    • First observedget_session_token_usage
    • First observedget_token_awareness_summary
Deploy Server
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • headroom

    tyejcoleman
    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.
    9 npm
    Apache 2.0

  • code-context-gate

    wisdomrock
    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