antigravity-usage 0.1.0 → 0.2.0

package/README.md

@@ -1,132 +1,204 @@
-# antigravity-usage
+<div align="center">
+    <img src="images/icon.png" alt="antigravity-usage logo" width="150" height="150">
+    <h1>antigravity-usage</h1>
+</div>
 
-CLI tool to check Antigravity model quota via Google Cloud Code API. Supports multiple Google accounts simultaneously.
+<p align="center">
+    <a href="https://npmjs.com/package/antigravity-usage"><img src="https://img.shields.io/npm/v/antigravity-usage?color=yellow" alt="npm version" /></a>
+    <a href="https://packagephobia.com/result?p=antigravity-usage"><img src="https://packagephobia.com/badge?p=antigravity-usage" alt="install size" /></a>
+    <a href="https://www.npmjs.com/package/antigravity-usage"><img src="https://img.shields.io/npm/dt/antigravity-usage" alt="NPM Downloads" /></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js Version" /></a>
+</p>
 
-Inspired by [ccusage](https://github.com/ryoppippi/ccusage).
+<p align="center">
+A fast, lightweight, and powerful CLI tool to track your Antigravity model quota and usage. Works offline with your IDE or online with multiple Google accounts.
+</p>
 
-## Installation
+<p align="center">
+<em>Inspired by <a href="https://github.com/ryoppippi/ccusage">ccusage</a></em>
+</p>
+
+<div align="center">
+    <img src="images/banner.png" alt="Antigravity Usage Screenshot">
+</div>
+
+
+## Quick Start (No Login Required) 🚀
+
+If you have Antigravity running in your IDE (VSCode, JetBrains, etc.), you can check your quota immediately **without logging in**.
 
 ```bash
+# Install globally
 npm install -g antigravity-usage
+
+# Check quota immediately (uses your IDE's connection)
+antigravity-usage
 ```
 
-## Quick Start
+That's it! The tool automatically connects to your local Antigravity server to fetch the exact same data your IDE sees.
 
+---
+
+## Power User Guide ⚡️
+
+Want to check quota for **multiple accounts** or when your IDE is closed?
+
+### 1. Login with Google
 ```bash
-# Login with your first account
 antigravity-usage login
+```
 
-# Add more accounts
+### 2. Add more accounts
+```bash
 antigravity-usage accounts add
+```
 
-# See quota for ALL accounts at once
+### 3. Check everything at once
+```bash
 antigravity-usage quota --all
-
-# Switch active account
-antigravity-usage accounts switch user@gmail.com
 ```
 
-## Commands
+---
 
-### `antigravity-usage accounts`
+## How It Works 🛠️
 
-Manage multiple Google accounts.
+Antigravity Usage employs a smart "Dual-Fetch" strategy to ensure you always get data:
 
-```bash
-antigravity-usage accounts list            # List all accounts & status
-antigravity-usage accounts add             # Add a new account (OAuth)
-antigravity-usage accounts switch <email>  # Set the active account
-antigravity-usage accounts remove <email>  # Remove an account & its data
-antigravity-usage accounts current         # Show active account info
-antigravity-usage accounts refresh --all   # Refresh tokens for all accounts
-```
+1.  **Local Mode (Priority)**: First, it tries to connect to the Antigravity Language Server running inside your IDE.
+    *   **Pros**: Fast, works offline, no extra login required.
+    *   **Cons**: IDE must be open.
+2.  **Cloud Mode (Fallback)**: If Local Mode fails (or if managing multiple accounts), it uses the Google Cloud Code API.
+    *   **Pros**: Works anywhere, supports multiple accounts.
+    *   **Cons**: Requires one-time login.
 
-### `antigravity-usage login`
+By default, `antigravity-usage` runs in **Auto Mode**, seamlessly switching between these methods.
 
-Authenticate with Google (adds to your accounts list).
+---
 
-```bash
-antigravity-usage login [options]
-```
+## Features
 
-- `--no-browser`: Print URL instead of opening browser
-- `-p, --port <port>`: Specify callback server port
+### 🔐 Multi-Account Management
+Seamlessly juggle multiple Google accounts (e.g., Personal vs Work).
+- **Parallel Fetching**: optional `--all` flag fetches data for all accounts simultaneously.
+- **Privacy Focused**: Tokens are stored locally on your machine, never sent to third-party servers.
 
-### `antigravity-usage quota`
+### 🔌 Offline Capabilities
+Designed for plane rides and spotty wifi.
+- **Direct IDE Access**: Reads directly from the local server loopback.
+- **Smart Fallbacks**: If the internet cuts out, it defaults to the last known state from your local IDE.
 
-Fetch and display quota information (default command).
+### ⚡️ Smart Caching
+To keep the CLI snappy and avoid hitting API rate limits:
+- Quota data is cached for **5 minutes**.
+- Use the `--refresh` flag to force a new fetch:
+    ```bash
+    antigravity-usage quota --refresh
+    ```
 
-```bash
-antigravity-usage quota [options]
-```
+### 📱 Responsive UI
+Tables automatically adapt to your terminal size, switching between "Compact" and "Spacious" views to show you the most relevant data without wrapping.
 
-Options:
-- `--all`: Fetch data for **all** accounts in parallel
-- `-a, --account <email>`: Fetch data for a specific account
-- `--refresh`: Force fresh data (ignore local cache)
-- `--json`: Output as JSON
-- `-m, --method <method>`: `auto` (default), `local`, or `google`
+---
 
-### `antigravity-usage status`
+## Command Reference
 
-Show authentication and token status.
+### `antigravity-usage` (Default)
+Alias for `quota`. Fetches and displays usage data.
 
 ```bash
-antigravity-usage status        # Status for active account
-antigravity-usage status --all  # Status for all accounts
+antigravity-usage                  # Auto-detect (Local -> Cloud)
+antigravity-usage --all            # Fetch ALL accounts
+antigravity-usage --method local   # Force local IDE connection
+antigravity-usage --method google   # Force google IDE connection
+antigravity-usage --json           # Output JSON for scripts
 ```
 
-### `antigravity-usage logout`
+### `antigravity-usage accounts`
+Manage your roster of Google accounts.
 
-Remove stored credentials.
+```bash
+antigravity-usage accounts list            # Show all accounts & status
+antigravity-usage accounts add             # Login a new account
+antigravity-usage accounts switch <email>  # Set active account
+antigravity-usage accounts remove <email>  # Logout & delete data
+```
+
+### `antigravity-usage doctor`
+Troubleshoot issues with your setup. Checks env vars, auth status, and local server connectivity.
+
+### `antigravity-usage status`
+Quickly check if your auth tokens are valid or expired.
+
+### `antigravity-usage wakeup` 🚀
+**Never waste quota again.** Automatically wake up your AI models at strategic times to maximize your daily limits.
 
 ```bash
-antigravity-usage logout [email]  # Logout specific account
-antigravity-usage logout --all    # Logout from all accounts
+antigravity-usage wakeup config     # Interactive setup (takes 30 seconds)
+antigravity-usage wakeup install    # Install to native system cron
+antigravity-usage wakeup status     # Check configuration & next run
+antigravity-usage wakeup test       # Test trigger manually
+antigravity-usage wakeup history    # View trigger history
 ```
 
-## Features
+**Why This Matters:**
+Your Antigravity quota resets every ~5 hours, but if you don't use it, you lose it. The wakeup feature ensures you **automatically trigger** both Claude and Gemini models to keep your quota flowing.
 
-### Smart Caching
-To keep things snappy when managing many accounts, the tool caches quota data for **5 minutes**.
-- Use `--refresh` to bypass the cache.
-- The cache is stored per-account.
+#### 🎯 Intelligent Model Selection
+Zero configuration needed. Automatically wakes up:
+- **`claude-sonnet-4-5`** → Triggers the entire Claude family
+- **`gemini-3-flash`** → Triggers the entire Gemini family
 
-### Offline Capabilities 🔌
-Antigravity Usage is designed to work seamlessly offline:
-1. **Local Method**: Reads directly from your IDE's language server (no internet required).
-2. **Caching**: If you're completely offline, you can still view the last known quota for all your accounts.
+Both models combined ensure comprehensive coverage and optimal quota utilization across all available AI models.
 
-### Responsive UI 📱
-Tables automatically adapt to your terminal size:
-- **Compact View**: For smaller screens or side-by-side terminals.
-- **Spacious View**: Optimizes layout for wide terminals.
-- **Auto-sizing**: Gracefully handles very small widths.
+#### ⚡️ Two Powerful Trigger Modes
 
-### Fetch Methods
-- **auto (default)**: Tries local Antigravity server first (offline), then falls back to Google API (online).
-- **local**: Only talks to your IDE's Antigravity server (**Offline**, no login needed).
-- **google**: Only talks to Google Cloud APIs (Online only).
+**1. Schedule-Based** (Native Cron Integration)
+Runs locally on your machine with zero dependencies:
+- **Interval Mode**: Every N hours (e.g., every 6 hours)
+- **Daily Mode**: At specific times (e.g., 9 AM, 5 PM)
+- **Custom Mode**: Advanced cron expressions for power users
 
----
+```bash
+antigravity-usage wakeup install
+# ✅ Installs to your system's native crontab
+# ✅ Runs even when terminal/antigravity is closed
+# ✅ Persists across reboots
+```
 
-## Configuration
+**2. Smart Quota-Reset Detection** (Zero-Waste Mode)
+The most intelligent trigger mode. Automatically detects when:
+- Quota is at **100%** (unused)
+- Reset time is **~5 hours away** (just reset)
+- No cooldown conflicts
+
+When triggered, it wakes up **ALL** your accounts simultaneously, ensuring none of your quota goes to waste.
+
+#### 🛡️ Built-in Safety Features
+- **Cooldown Protection**: Prevents duplicate triggers (1-hour default)
+- **Multi-Account Support**: Trigger for specific accounts or all at once
+- **Detailed History**: Track every trigger with timestamps and results
+- **Graceful Failures**: Automatic retry logic with exponential backoff
+- **Token Efficiency**: Minimal output tokens (just 1 token per request)
 
-### OAuth Credentials
-The tool works out of the box with built-in credentials. To use your own:
+#### 📊 Real-Time Monitoring
 ```bash
-export ANTIGRAVITY_OAUTH_CLIENT_ID="..."
-export ANTIGRAVITY_OAUTH_CLIENT_SECRET="..."
+antigravity-usage wakeup status
 ```
+Shows:
+- ✅ Enabled/disabled status
+- 📅 Next scheduled run time
+- 🎯 Selected models and accounts
+- 📝 Last trigger result
+- ⚙️ Cron installation status
 
-### Token Storage
-Data is stored in your system's config directory:
-- **macOS**: `~/Library/Application Support/antigravity-usage/accounts/`
-- **Linux**: `~/.config/antigravity-usage/accounts/`
-- **Windows**: `%APPDATA%/antigravity-usage/accounts/`
+## Configuration
+Data is stored in your system's standard config location:
+- **macOS**: `~/Library/Application Support/antigravity-usage/`
+- **Linux**: `~/.config/antigravity-usage/`
+- **Windows**: `%APPDATA%/antigravity-usage/`
 
 ## Development
-
 ```bash
 npm run dev -- quota --all
 npm test