{"slug": "preventing-quota-crashes-via-antigravity-cli-agent-hooks", "title": "Preventing Quota Crashes via Antigravity CLI Agent Hooks", "summary": "Google Antigravity CLI users face abrupt task failures when API quota hits 0%, and account switching triggers unrecoverable signature errors. To solve this, a developer built antigravity-cli-check-usage-plugin, a CLI Agent Hook that runs outside the LLM execution turn, directly querying local Connect RPC endpoints to monitor quota with zero token overhead and inject proactive warning banners.", "body_md": "Google Antigravity CLI users using Google OAuth face abrupt task failures when API quota hits 0%, while account switching triggers unrecoverable signature errors. Querying quota via LLM tool calls creates a paradox by consuming the very tokens being monitored. We resolve this with `antigravity-cli-check-usage-plugin`\n\n, a CLI Agent Hook running outside the LLM execution turn. Directly querying local Connect RPC endpoints, it monitors quota with zero token overhead and injects proactive warning banners when threshold limits are reached.\n\nDevelopers relying on **Google Antigravity CLI** for autonomous pair programming frequently encounter a frustrating barrier: running out of API quota mid-session. When using Google OAuth authentication, your quota can silently hit 0%, causing task execution to halt abruptly with an unrecoverable quota error:\n\n```\n⚠ Individual quota reached. Please upgrade your subscription to increase your limits. Resets in 1h00m00s.\nError ID: 49a81c0f\n```\n\nTo bypass this roadblock, developers often attempt to log out and switch to a paid Google Cloud project billing account. However, in **Antigravity CLI v1.1.12**, attempting to resume an active agent session after switching accounts triggers a critical signature mismatch failure:\n\n```\n⚠ Invalid thought signature.\nError ID: e2901f4c\n```\n\nThis error prevents the session from continuing, forcing you to wait until the quota resets. While future CLI updates may resolve this session state issue, waiting for a patch is not a viable strategy when shipping code today.\n\nThe architectural divergence between standard tool-based monitoring and our agent hook model is illustrated in Figure 1. While developers can manually run the `/usage`\n\nslash command to view quota, **AI agents executing multi-step autonomous tasks cannot trigger /usage programmatically**. In traditional CLI workflows, invoking quota checks via LLM tool calls requires passing context back and forth through the inference API, depleting active model tokens. Conversely, the zero-overhead agent hook interceptor executes locally prior to prompt dispatch, querying the process socket silently and injecting status alerts only when remaining quota breaches configured safety bounds.\n\nIn this article, to overcome the limitation of agents being unable to trigger `/usage`\n\n, we walk through the engineering journey of building ** antigravity-cli-check-usage-plugin**. By combining local Connect RPC inspection with proactive lifecycle hooks, this plugin automatically performs external quota checks with\n\nThe plugin developed and discussed in this article is open-sourced and available on GitHub:\n\nThis repository contains the dual-runner entrypoint (`entrypoint.sh`\n\n), Python script (`check_quota.py`\n\n), pure Bash fallback script (`check_quota.sh`\n\n), lifecycle hook manifest (`hooks.json`\n\n), and default threshold configuration (`config.json`\n\n), allowing instant one-command installation as an Antigravity CLI plugin across any developer environment.\n\nWhile Antigravity CLI provides the `/usage`\n\nslash command for developers to manually inspect quota limits, AI agents executing autonomous task loops cannot invoke `/usage`\n\nprogrammatically.\n\nIf we attempted to solve this by equipping the AI agent with a custom tool to query the internal RPC endpoint (`/exa.language_server_pb.LanguageServerService/GetUserStatus`\n\n), the tool invocation and context turns would consume LLM API tokens. This creates a fundamental paradox: **using LLM context tokens to check remaining quota consumes the very quota you are trying to preserve.**\n\nIn addressing this challenge, the solution built upon our previously published article, [A Developer’s Guide to Agent Hooks in Antigravity CLI](https://medium.com/google-cloud/a-developers-guide-to-agent-hooks-in-antigravity-cli-4c1440febd11). Recalling the out-of-band execution mechanics of CLI Agent Hooks explored in that guide, we leveraged lifecycle events (`PreInvocation`\n\nand `PostInvocation`\n\n) to run local process checks completely outside the LLM inference turn—guaranteeing zero API token quota overhead.\n\n`127.0.0.1`\n\nwithout external network calls.Through reverse-engineering the Antigravity CLI local process architecture (originally explored in the [antigravity-usage repository by skainguyen1412](https://github.com/skainguyen1412/antigravity-usage)), we discovered that the running `agy`\n\nprocess hosts a local HTTPS server using the gRPC / Connect Protocol on `127.0.0.1`\n\n.\n\nBy querying the internal endpoint `/exa.language_server_pb.LanguageServerService/GetUserStatus`\n\n, we can retrieve real-time model quota fractions and reset timestamps directly from the local process.\n\nBecause the `agy`\n\nprocess may open multiple listening sockets on `127.0.0.1`\n\nfor IPC and WebSockets, a shell loop that probes each detected port until it receives a valid `userStatus`\n\nresponse is required:\n\n```\n# Scan listening sockets for the active 'agy' process on loopback (127.0.0.1)\nfor PORT in $(ss -tulpn 2>/dev/null | grep agy | awk -F'127.0.0.1:' '{print $2}' | awk '{print $1}' | sort -u); do\n  # Post a Connect Protocol request to the internal GetUserStatus RPC endpoint\n  RES=$(curl -k -s -X POST https://127.0.0.1:${PORT}/exa.language_server_pb.LanguageServerService/GetUserStatus \\\n    -H \"Content-Type: application/json\" \\\n    -H \"Connect-Protocol-Version: 1\" \\\n    -d '{\"metadata\":{\"ideName\":\"antigravity\",\"extensionName\":\"antigravity\",\"locale\":\"en\"}}')\n\n  # Verify if the response contains the userStatus JSON key\n  if echo \"$RES\" | grep -q \"userStatus\"; then\n    echo \"$RES\" | jq .\n    break\n  fi\ndone\n```\n\nTo execute this logic seamlessly and rapidly inside an agent hook outside the LLM invocation turn, we implemented a Python script using standard library components, alongside a pure Bash fallback script (`check_quota.sh`\n\n) and an entrypoint runner (`entrypoint.sh`\n\n) that automatically selects Python when available or Bash on systems without Python installed.\n\n[!IMPORTANT]\n\nNote on Scope: The`GetUserStatus`\n\nendpoint returns theFive Hour Limit Remainingfraction (`remainingFraction`\n\n) and ISO reset timestamp (`resetTime`\n\n) for active model pools. The long-termWeekly Limit Remainingis not exposed through this RPC endpoint.\n\nBuilding upon the lifecycle concepts detailed in [A Developer’s Guide to Agent Hooks in Antigravity CLI](https://medium.com/google-cloud/a-developers-guide-to-agent-hooks-in-antigravity-cli-4c1440febd11), the plugin integrates into the Antigravity CLI by registering `PreInvocation`\n\nand `PostInvocation`\n\nagent hooks in `hooks.json`\n\n. Because `PreInvocation`\n\nfires after the user submits input but *before* the prompt payload is dispatched to the LLM backend, it inspects local process state and dynamically injects steps prior to model inference.\n\nAs detailed in Figure 2, the final agent hook operates under two distinct execution patterns based on the configured warning threshold (default: 20%):\n\nWhen remaining quota is above the warning threshold, the hook outputs an empty step injection payload:\n\n```\n{\n  \"injectSteps\": []\n}\n```\n\nWhen remaining quota drops to or below the threshold, the hook injects a transient system message with mandatory agent directives:\n\n```\n{\n  \"injectSteps\": [\n    {\n      \"ephemeralMessage\": \"⚠️ [SYSTEM QUOTA WARNING] Model quota is below threshold (20%) (Active: gemini-3.6-flash-medium):\\n - GEMINI Models [ACTIVE MODEL]: 20.0% remaining (Refreshes in 3h 00m)\\n\\n[MANDATORY INSTRUCTION FOR AGENT]: The model quota has dropped below the threshold. You MUST display a prominent Quota Warning banner at the very top of your response for THIS TURN ONLY! Do NOT display a warning banner on subsequent turns unless another quota warning is explicitly injected. In the warning banner, you MUST also inform the user that they can run the '/usage' command at any time to inspect detailed quota status.\"\n    }\n  ]\n}\n```\n\n`/usage`\n\nor pause heavy multi-step automation before encountering a hard crash.The complete implementation is published as an open-source Antigravity CLI plugin: `antigravity-cli-check-usage-plugin`\n\n.\n\nInstall the plugin directly via the Antigravity CLI:\n\n```\nagy plugin install https://github.com/tanaikech/antigravity-cli-check-usage-plugin\n```\n\nThe plugin features a multi-environment entrypoint (`entrypoint.sh`\n\n) producing 100% identical JSON outputs across both runtimes. The engineering rationale behind this dual design includes:\n\n`jq`\n\n, absorbs OS-specific syntax differences across Linux, macOS, and Windows, and guarantees type-safe date math.You can customize or completely disable the warning threshold (default: **20.0%**) using environment variables, configuration files, or hook arguments.\n\n**Set Custom Threshold (e.g., 25%):**\n\n```\nexport QUOTA_THRESHOLD=25.0\n```\n\n**Disable Quota Check Completely:**\n\nSetting `QUOTA_THRESHOLD`\n\nto `-1`\n\ninstructs the hook to skip all RPC queries immediately:\n\n```\nexport QUOTA_THRESHOLD=-1\n```\n\nAfter installing the plugin, setting `export QUOTA_THRESHOLD=80.0`\n\nand executing a live session test in Antigravity CLI v1.1.12 demonstrates the hook in action, as captured in Figure 3:\n\nWhen the user enters a simple greeting (`hello`\n\n), the agent hook instantly detects that the active model's remaining quota (71.0%) has dropped below the configured threshold (80.0%). A prominent yellow **Warning banner** (`Quota Warning: GEMINI Models quota is at 71.0% remaining...`\n\n) is dynamically prepended at the top of the AI's response, alerting the developer and providing a reminder to inspect detailed limits via `/usage`\n\n.\n\nTo update the plugin to the latest version or remove it from your environment:\n\n```\n  agy plugin list\nagy plugin uninstall antigravity-cli-check-usage-plugin\nagy plugin install https://github.com/tanaikech/antigravity-cli-check-usage-plugin\n```\n\nIn this article, we presented a zero-overhead solution to eliminate mid-session quota crashes and account-switching signature errors in Google Antigravity CLI. Drawing upon foundational concepts from [A Developer’s Guide to Agent Hooks in Antigravity CLI](https://medium.com/google-cloud/a-developers-guide-to-agent-hooks-in-antigravity-cli-4c1440febd11) and resolving the paradox where using LLM tool calls to query internal RPC endpoints consumes quota, we built native CLI Agent Hooks (`PreInvocation`\n\n/ `PostInvocation`\n\n) running completely outside the LLM execution turn. Featuring a dual Python primary and pure Bash fallback architecture, the hook probes internal local Connect RPC endpoints with absolute zero token consumption during normal operation. By proactively injecting warning banners and `/usage`\n\nreminders when quota drops below threshold, it guarantees universal environment compatibility and eliminates task interruptions cleanly at the root.", "url": "https://wpnews.pro/news/preventing-quota-crashes-via-antigravity-cli-agent-hooks", "canonical_source": "https://dev.to/gde/preventing-quota-crashes-via-antigravity-cli-agent-hooks-24hd", "published_at": "2026-08-12 07:15:38+00:00", "updated_at": "2026-08-12 07:46:58.136079+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-infrastructure"], "entities": ["Google Antigravity CLI", "antigravity-cli-check-usage-plugin", "Google OAuth", "Google Cloud"], "alternates": {"html": "https://wpnews.pro/news/preventing-quota-crashes-via-antigravity-cli-agent-hooks", "markdown": "https://wpnews.pro/news/preventing-quota-crashes-via-antigravity-cli-agent-hooks.md", "text": "https://wpnews.pro/news/preventing-quota-crashes-via-antigravity-cli-agent-hooks.txt", "jsonld": "https://wpnews.pro/news/preventing-quota-crashes-via-antigravity-cli-agent-hooks.jsonld"}}