Preventing Quota Crashes via Antigravity CLI Agent Hooks

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.

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 , 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. Developers 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: ⚠ Individual quota reached. Please upgrade your subscription to increase your limits. Resets in 1h00m00s. Error ID: 49a81c0f To 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: ⚠ Invalid thought signature. Error ID: e2901f4c This 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. The architectural divergence between standard tool-based monitoring and our agent hook model is illustrated in Figure 1. While developers can manually run the /usage slash 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. In this article, to overcome the limitation of agents being unable to trigger /usage , 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 The plugin developed and discussed in this article is open-sourced and available on GitHub: This repository contains the dual-runner entrypoint entrypoint.sh , Python script check quota.py , pure Bash fallback script check quota.sh , lifecycle hook manifest hooks.json , and default threshold configuration config.json , allowing instant one-command installation as an Antigravity CLI plugin across any developer environment. While Antigravity CLI provides the /usage slash command for developers to manually inspect quota limits, AI agents executing autonomous task loops cannot invoke /usage programmatically. If 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 , 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. In 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 and PostInvocation to run local process checks completely outside the LLM inference turn—guaranteeing zero API token quota overhead. 127.0.0.1 without 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 process hosts a local HTTPS server using the gRPC / Connect Protocol on 127.0.0.1 . By querying the internal endpoint /exa.language server pb.LanguageServerService/GetUserStatus , we can retrieve real-time model quota fractions and reset timestamps directly from the local process. Because the agy process may open multiple listening sockets on 127.0.0.1 for IPC and WebSockets, a shell loop that probes each detected port until it receives a valid userStatus response is required: Scan listening sockets for the active 'agy' process on loopback 127.0.0.1 for PORT in $ ss -tulpn 2 /dev/null | grep agy | awk -F'127.0.0.1:' '{print $2}' | awk '{print $1}' | sort -u ; do Post a Connect Protocol request to the internal GetUserStatus RPC endpoint RES=$ curl -k -s -X POST https://127.0.0.1:${PORT}/exa.language server pb.LanguageServerService/GetUserStatus \ -H "Content-Type: application/json" \ -H "Connect-Protocol-Version: 1" \ -d '{"metadata":{"ideName":"antigravity","extensionName":"antigravity","locale":"en"}}' Verify if the response contains the userStatus JSON key if echo "$RES" | grep -q "userStatus"; then echo "$RES" | jq . break fi done To 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 and an entrypoint runner entrypoint.sh that automatically selects Python when available or Bash on systems without Python installed. IMPORTANT Note on Scope: The GetUserStatus endpoint returns theFive Hour Limit Remainingfraction remainingFraction and ISO reset timestamp resetTime for active model pools. The long-termWeekly Limit Remainingis not exposed through this RPC endpoint. Building 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 and PostInvocation agent hooks in hooks.json . Because PreInvocation fires 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. As detailed in Figure 2, the final agent hook operates under two distinct execution patterns based on the configured warning threshold default: 20% : When remaining quota is above the warning threshold, the hook outputs an empty step injection payload: { "injectSteps": } When remaining quota drops to or below the threshold, the hook injects a transient system message with mandatory agent directives: { "injectSteps": { "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." } } /usage or 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 . Install the plugin directly via the Antigravity CLI: agy plugin install https://github.com/tanaikech/antigravity-cli-check-usage-plugin The plugin features a multi-environment entrypoint entrypoint.sh producing 100% identical JSON outputs across both runtimes. The engineering rationale behind this dual design includes: jq , 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. Set Custom Threshold e.g., 25% : export QUOTA THRESHOLD=25.0 Disable Quota Check Completely: Setting QUOTA THRESHOLD to -1 instructs the hook to skip all RPC queries immediately: export QUOTA THRESHOLD=-1 After installing the plugin, setting export QUOTA THRESHOLD=80.0 and executing a live session test in Antigravity CLI v1.1.12 demonstrates the hook in action, as captured in Figure 3: When the user enters a simple greeting hello , 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... is dynamically prepended at the top of the AI's response, alerting the developer and providing a reminder to inspect detailed limits via /usage . To update the plugin to the latest version or remove it from your environment: agy plugin list agy plugin uninstall antigravity-cli-check-usage-plugin agy plugin install https://github.com/tanaikech/antigravity-cli-check-usage-plugin In 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 / PostInvocation 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 reminders when quota drops below threshold, it guarantees universal environment compatibility and eliminates task interruptions cleanly at the root.