usage-google-opencode

🔍 CLI tool for checking Google Cloud Code Assist quota usage

Track your quota usage across two Google Cloud identities:

• Antigravity (IDE client quota)
• Gemini CLI (CLI client quota)

Built with AI assistance and designed for developers using Google Cloud Code Assist.

---

✨ Features

• 🔐 Secure OAuth2 authentication with Google
• 📊 Real-time quota monitoring for both IDE and CLI identities
• 🎯 Filters for Gemini, Claude, and image generation AI models
• 📋 Beautiful table output or JSON for automation
• 🔄 Automatic token refresh
• 💾 Secure local storage with proper file permissions
• ⚡ Fast parallel quota fetching

---

📦 Installation

Requirements

• Node.js 20+ or Bun
• A Google account authorized for Code Assist

Install Locally

Using npm:

npm install
npm run build

Using bun:

bun install
bun run build

Global Installation

Using npm:

npm install
npm run build
npm link

Using bun:

bun install
bun run build
bun pm pack
bun install -g "$(pwd)/usage-google-opencode-1.2.2.tgz"

Make sure ~/.bun/bin is in your PATH:

export PATH="$HOME/.bun/bin:$PATH"

Uninstall

Using npm:

npm unlink -g usage-google-opencode
# or, from this repo:
npm unlink

Using bun:

bun remove -g usage-google-opencode

---

🚀 Usage

Login

Antigravity only:

usage-google login --mode antigravity

Gemini CLI (requires GCP project ID):

usage-google login --mode gemini-cli --project my-gcp-projectID

Both identities (recommended):

usage-google login --mode both --project my-gcp-projectID

💡 Tip: Get your GCP project ID with: gcloud config get-value project

Check Quota Status

Default table view:

usage-google status

JSON output (for automation):

usage-google status --format json

Filter by identity:

usage-google status --only antigravity
usage-google status --only gemini-cli

Filter by account:

usage-google status --account user@example.com

---

📖 Examples

Quick Start

# Login with both identities
usage-google login --mode both --project my-project-123

# Check your quota
usage-google status

Output Example

Summary

┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Email                  Identity      Model                      Remaining  Reset      Status        │
├────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ user@example.com       antigravity   claude-opus-4-6-thinking   100%       2h30m      OK            │
│ user@example.com       antigravity   gemini-3.1-flash-image     95%        2h30m      OK            │
│ user@example.com       gemini-cli    gemini-3.1-pro-preview     100%       23h45m     OK            │
└────────────────────────────────────────────────────────────────────────────────────────────────────┘

---

🔒 Security & Privacy

Stored Data

• Location: ~/.config/opencode/usage-google-accounts.json
• Contains: Refresh tokens and email addresses
• Permissions: Automatically set to 0600 (owner read/write only)

What's Stored

{
  "version": 1,
  "accounts": [
    {
      "email": "user@example.com",
      "antigravity": {
        "refreshToken": "...",
        "cachedAccessToken": "...",
        "cachedExpiresAt": 1234571490
      },
      "geminiCli": {
        "refreshToken": "...",
        "projectId": "my-project",
        "cachedAccessToken": "...",
        "cachedExpiresAt": 1234571490
      },
      "addedAt": 1234567890,
      "updatedAt": 1234567890
    }
  ]
}

Privacy Notes

• Refresh tokens are securely stored with restrictive file permissions
• Access tokens are cached locally to speed up subsequent runs (valid ~1 hour, auto-refreshed when expired)
• Email addresses are displayed in status output
• Never commit the storage file to version control
• Never share the storage file

OAuth Credentials

The OAuth client IDs and secrets are hardcoded by design. These are public client credentials extracted from:

• Antigravity IDE (for IDE quota)
• Google Cloud SDK / Gemini CLI (for CLI quota)

This is standard practice for OAuth public clients and poses no security risk.

---

⚙️ Configuration

Storage File

Default location: ~/.config/opencode/usage-google-accounts.json

• macOS/Linux: ~/.config/opencode/
• Windows: %APPDATA%\opencode\

Network Timeouts

• Token refresh timeout: 10 seconds per request
• Endpoint timeout: 15 seconds per request (with retry up to 3 times for both identities)
• Login timeout: 2 minutes for OAuth callback
• Token caching: Access tokens are cached locally and reused for up to 55 minutes (5-minute safety margin before expiry), eliminating one network round-trip on subsequent runs

Quota Reset Times

• Displayed as 2h30m for times under 24 hours
• Switches to 1d5h30m format for times over 24 hours
• Shows now for expired quotas

---

🛠️ Development

Run Tests

npm test        # or: bun test

Type Check

npm run typecheck

Build

npm run build

Run Locally

node dist/index.js status

---

📝 Known Limitations

• Concurrent login commands may cause storage corruption (atomic writes mitigate this in v1.0.0+)
• Network requests timeout after 15 seconds; both identities retry up to 3 times (403 errors throw immediately)
• Gemini CLI quota requires a GCP project ID

---

📄 License

MIT License - See LICENSE file for details

---

🙏 Acknowledgments

• Built with assistance from AI
• OAuth credentials extracted from official Google Cloud SDK and Antigravity IDE
• Uses Google Cloud Code Assist internal APIs

---

📞 Support

• Issues: Report bugs or request features
• Documentation: See docs/ directory for implementation details

---

🔄 Changelog

See CHANGELOG.md for version history and updates.

---

⭐ If this tool helps you, consider giving it a star! ⭐

Made with ❤️ and AI assistance