antigravity-usage 0.1.1 → 0.2.1

package/README.md

@@ -1,8 +1,28 @@
-# Antigravity Usage
-
+<div align="center">
+    <img src="images/icon.png" alt="antigravity-usage logo" width="150" height="150">
+    <h1>antigravity-usage</h1>
+</div>
+
+<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>
+
+<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>
+
+<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>
 
-Inspired by [ccusage](https://github.com/ryoppippi/ccusage).
 
 ## Quick Start (No Login Required) 🚀
 
@@ -39,8 +59,6 @@ antigravity-usage accounts add
 antigravity-usage quota --all
 ```
 
-![Demo](https://via.placeholder.com/800x400?text=Antigravity+Usage+CLI+Demo)
-
 ---
 
 ## How It Works 🛠️
@@ -89,10 +107,19 @@ Tables automatically adapt to your terminal size, switching between "Compact" an
 Alias for `quota`. Fetches and displays usage data.
 
 ```bash
-antigravity-usage                  # Auto-detect (Local -> Cloud)
-antigravity-usage --all            # Fetch ALL accounts
-antigravity-usage --method local   # Force local IDE connection
-antigravity-usage --json           # Output JSON for scripts
+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 --version         # Show version number
+```
+
+### `antigravity-usage --version`
+Display the current version of the CLI tool.
+
+```bash
+antigravity-usage --version  # or -V
 ```
 
 ### `antigravity-usage accounts`
@@ -111,6 +138,68 @@ Troubleshoot issues with your setup. Checks env vars, auth status, and local ser
 ### `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 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
+```
+
+**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.
+
+#### 🎯 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
+
+Both models combined ensure comprehensive coverage and optimal quota utilization across all available AI models.
+
+#### ⚡️ Two Powerful Trigger Modes
+
+**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
+```
+
+**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)
+
+#### 📊 Real-Time Monitoring
+```bash
+antigravity-usage wakeup status
+```
+Shows:
+- ✅ Enabled/disabled status
+- 📅 Next scheduled run time
+- 🎯 Selected models and accounts
+- 📝 Last trigger result
+- ⚙️ Cron installation status
+
 ## Configuration
 Data is stored in your system's standard config location:
 - **macOS**: `~/Library/Application Support/antigravity-usage/`