Antigravity Tools

Antigravity Tools (v4.5.4) is a professional-grade AI account management and protocol proxy system. It acts as a high-performance local AI scheduling gateway that allows developers to manage multiple AI accounts and convert web-based sessions (such as Google or Anthropic) into standardized API interfaces.

Key capabilities include:

• Account Management: OAuth 2.0 authorization, multi-dimensional import (Token, JSON, or V1 database migration), and automated 403 error detection.
• Protocol Proxying: Supports OpenAI (/v1/chat/completions), Anthropic (/v1/messages), and Gemini formats.
• Smart Routing: Model mapping via regex, tiered routing based on account types (Ultra/Pro/Free), and automatic silent degradation for background tasks.
• Self-Healing: Automatic retries and silent rotation when encountering 429 (Too Many Requests) or 401 (Expire) errors.

The proxy includes a robust failover mechanism for handling API errors. When the system encounters specific error codes, it triggers an automatic account rotation:

• Trigger Errors: 429 (Rate Limit), 403 (Forbidden), and 401 (Expired).
• Behavior: The retry mechanism force-bypasses the 60s session lock and immediately rotates to the next available account in your configured account pool.
• Background Task Optimization: For low-value requests (e.g., title generation, summaries, or system warmups), the system can automatically redirect traffic to gemini-2.5-flash to preserve high-value quotas (like Sonnet/Opus) for core tasks.

The ClientAdapter framework is designed to decouple handler logic from specific downstream client requirements, ensuring thread-safe sharing and high stability. It provides seamless integration for four primary protocols: Claude, OpenAI, Gemini, and OA-Compatible.

Key Features for Developers:

• Thread Safety: Uses Arc reference counting for safe sharing across threads.
• Error Handling: Implements a let_it_crash fail-fast mechanism and standardized error responses (supporting both SSE event: error and non-stream JSON) so third-party clients can correctly parse upstream exceptions.
• Concurrency Management: Uses FIFO signature buffering to manage high-concurrency scenarios.
• Session Isolation: Uses SignatureCache and session_id to physically isolate thinking signatures, preventing cross-contamination in multi-turn or concurrent sessions.

The system refactors multi-segment system or developer prompts into a standardized XML structure using the Antigravity style. These are sent as a single part with role = "system". The supported tags include:

• <identity>
• <user_information>
• <environment_permissions>
• <skills>
• <planning_mode>

When using the v1internal protocol with Gemini models, be aware of specific tool limitations. The protocol does not support using googleSearch and functionDeclarations simultaneously.

To prevent 400 INVALID_ARGUMENT errors, the proxy implements Smart Injection: if a request contains function definitions, the proxy automatically skips the injection of the Google Search tool to ensure request success.

The system distinguishes between different Gemini API response formats to prevent double-counting tokens:

• AI Studio (Official API): Uses candidatesTokenCount (which includes thought tokens).
• Vertex AI (Interactions API): Uses total_output_tokens (which does not include thought tokens).

The extract_output_tokens logic in monitor.rs ensures that thoughtsTokenCount is not erroneously added to candidatesTokenCount during streaming (SSE) or standard JSON responses.

To save high-value tokens (e.g., for Sonnet or Opus models), Antigravity Tools implements an intelligent 'Token Saver' mechanism. The system identifies low-value background tasks such as:

• Title generation
• Summary extraction
• System Warmup/Reminder tasks

These tasks are automatically redirected to gemini-2.5-flash instead of your primary high-performance models, significantly reducing token consumption for long sessions.

The Model Router allows you to manage how incoming requests are directed to specific upstream models through several mechanisms:

• Series Mapping: Group complex original model IDs into "specification families" (e.g., routing all GPT-4 requests to a specific gemini-3-pro-high model).
• Expert Redirection: Use custom regular expression-based model mapping for precise control over which model handles which request.
• Tiered Routing: The system automatically prioritizes accounts based on their type (Ultra, Pro, or Free) and quota reset frequency. It prioritizes high-speed reset accounts to ensure stability during high-frequency calls.
• Silent Degradation: The system can identify background requests (such as title generation from Claude CLI) and automatically redirect them to lighter models (like Flash) to preserve high-tier model quotas.

The system optimizes model usage and quota preservation through several automated mechanisms:

• Smart Downgrading: Background tasks (such as generating titles or summaries for Claude CLI/Agents) are automatically rerouted to Flash models to prevent the consumption of premium or long-context quotas.
• Tiered Account Sorting: Model routes are automatically sorted by quota reset frequency: ULTRA > PRO > FREE. This prioritizes accounts that reset frequently (e.g., hourly) and reserves FREE accounts as a final safety net.
• Concurrency Protection: The TokenManager uses atomic session locks to ensure stable account assignment during high-concurrency scenarios (like Agent mode), preventing account quota overflow and unnecessary account rotations.

Antigravity Tools uses two different authentication methods depending on whether you are calling the AI Proxy or the Management Admin API. All services are unified on port 8045.

Note: By default, the Admin Token and API Key are the same value (the API_KEY set in your .env or Docker environment variables).

# Example AI Protocol Call
POST /v1/chat/completions
Authorization: Bearer YOUR_API_KEY

# Example Admin API Call
GET /api/accounts
x-admin-token: YOUR_API_KEY

To improve the stability of thinking models during multi-turn conversations, Antigravity Tools uses a three-layer signature caching architecture:

1. Layer 1: Tool Signatures
2. Layer 2: Thinking Families
3. Layer 3: Session Signatures

Session Isolation: A stable session_id is generated by taking the SHA256 hash of the first user message. This ensures that all turns within the same conversation use the same session identifier, allowing the system to automatically recover thinking signatures during tool calls and multi-turn dialogues. The lookup priority is: Session Cache $\rightarrow$ Tool Cache $\rightarrow$ Global Store.