AI Usage Monitor

A single-binary Bun application that monitors AI usage across multiple providers with a beautiful graphite-themed dashboard.

Features

📊 Real-time Dashboard: Beautiful graphite-themed UI with live usage data
🔌 Multi-Provider Support: Anthropic Claude, OpenRouter, GitHub Copilot, Google AI, Z.ai, Vercel, and Warp.dev
⚡ High Performance: Built with Bun for lightning-fast execution
💾 Smart Caching: Reduces API calls with configurable TTL (default 5 minutes)
🔄 Auto-Refresh: Automatically updates data every 5 minutes
📈 Visual Analytics: Interactive charts showing usage trends and distributions
🚀 Single Binary: Compile to a standalone executable for easy deployment
🛡️ Error Resilient: Gracefully handles provider failures without crashing

Quick Start

Prerequisites

Bun installed on your system
API keys for the AI providers you want to monitor

Installation

Clone the repository:

git clone <repository-url>
cd ai-usage-monitor

Install dependencies:

bun install

Configure environment variables:

cp .env.example .env

Edit .env and add your API keys:

ANTHROPIC_API_KEY=your_anthropic_api_key_here
OPENROUTER_API_KEY=your_openrouter_api_key_here
GITHUB_TOKEN=your_github_token_here
GOOGLE_AI_API_KEY=your_google_ai_api_key_here
ZAI_API_KEY=your_zai_api_key_here
VERCEL_TOKEN=your_vercel_token_here

(Optional) If using OpenRouter or Z.ai via the API key storage system:

cp data/api-keys.json.example data/api-keys.json

Edit data/api-keys.json with your keys:

{
  "openrouter": "sk-or-v1-your-key-here",
  "zai": "your-zai-api-key-here"
}

Run in development mode:

bun run dev

Open your browser and navigate to:

http://localhost:3000

Building for Production

Create a Single Binary

bun run build

This creates a standalone ai-usage-monitor binary that includes all dependencies.

Run the Binary

./ai-usage-monitor

The binary will:

Start the HTTP server on port 3000 (configurable via PORT env var)
Serve the dashboard at http://localhost:3000
Fetch usage data from configured providers
Cache results for 5 minutes (configurable via CACHE_TTL env var)

Configuration

Environment Variables

Variable	Required	Default	Description
`PORT`	No	`3000`	HTTP server port
`HOST`	No	`localhost`	HTTP server hostname
`ANTHROPIC_API_KEY`	No	-	Anthropic Claude API key
`OPENROUTER_API_KEY`	No	-	OpenRouter API key
`GITHUB_TOKEN`	No	-	GitHub Personal Access Token (for Copilot)
`GOOGLE_AI_API_KEY`	No	-	Google AI (Gemini) API key
`ZAI_API_KEY`	No	-	Z.ai API key
`VERCEL_TOKEN`	No	-	Vercel API token
`CACHE_TTL`	No	`300`	Cache time-to-live in seconds
`LOG_LEVEL`	No	`info`	Logging level (trace, debug, info, warn, error, fatal)

Provider Setup

Anthropic Claude

Go to console.anthropic.com
Create an account or sign in
Navigate to API Keys section
Generate a new API key
Add to .env: ANTHROPIC_API_KEY=sk-ant-...

OpenRouter

Go to openrouter.ai/keys
Sign in or create an account
Generate a new API key
Add to .env: OPENROUTER_API_KEY=sk-or-...

GitHub Copilot

Go to github.com/settings/tokens
Generate a new Personal Access Token
Select scopes: read:org and read:user
Add to .env: GITHUB_TOKEN=ghp_...

Google AI (Gemini)

Go to makersuite.google.com/app/apikey
Sign in with your Google account
Create a new API key
Add to .env: GOOGLE_AI_API_KEY=AIza...

Z.ai

Contact Z.ai for API access
Obtain your API key
Add to .env: ZAI_API_KEY=your_key_here

Vercel

Go to vercel.com/account/tokens
Create a new token
Add to .env: VERCEL_TOKEN=your_token_here

Warp.dev (macOS only)

Warp requires special setup since it uses Firebase authentication stored in the macOS Keychain.

Quick Setup:

./scripts/extract-warp-token.sh

This will automatically extract your Warp token and add it to .env.

Requirements:

macOS (Warp stores tokens in macOS Keychain)
Warp installed and you must be signed in
Token expires periodically - re-run the script when needed

For detailed instructions, see docs/WARP_SETUP.md

API Endpoints

GET /api/usage

Get aggregated usage data from all providers.

Query Parameters:

days (optional): Number of days to fetch data for (default: 7)

Response:

{
  "success": true,
  "data": {
    "summary": {
      "totalRequests": 2400000,
      "totalCost": 847.32,
      "totalTokens": 847000000,
      "avgLatency": 1.2,
      "requestChange": 12.5,
      "costChange": 8.3,
      "tokenChange": 23.1,
      "latencyChange": -5.4
    },
    "providers": [
      {
        "id": "anthropic",
        "name": "Anthropic Claude",
        "requests": 847000,
        "cost": 234.50,
        "tokens": 284000000,
        "status": "active",
        "lastUpdated": "2026-01-08T14:00:00Z"
      }
    ],
    "timeline": [
      {
        "date": "Jan 1",
        "requests": 320000,
        "cost": 95.00
      }
    ],
    "lastUpdated": "2026-01-08T14:30:00Z"
  },
  "timestamp": "2026-01-08T14:30:00Z"
}

GET /api/usage/:providerId

Get usage data for a specific provider.

Query Parameters:

days (optional): Number of days to fetch data for (default: 7)

Response:

{
  "success": true,
  "data": {
    "id": "anthropic",
    "name": "Anthropic Claude",
    "requests": 847000,
    "cost": 234.50,
    "tokens": 284000000,
    "status": "active",
    "lastUpdated": "2026-01-08T14:00:00Z"
  },
  "timestamp": "2026-01-08T14:30:00Z"
}

GET /api/health

Check health status of all configured providers.

Response:

{
  "success": true,
  "data": {
    "anthropic": true,
    "openrouter": true,
    "copilot": false,
    "google": true,
    "zai": true,
    "vercel": true
  },
  "timestamp": "2026-01-08T14:30:00Z"
}

GET /api/providers

List all configured providers and their health status.

Response:

{
  "success": true,
  "data": {
    "anthropic": true,
    "openrouter": true,
    "copilot": false,
    "google": true,
    "zai": true,
    "vercel": true
  },
  "timestamp": "2026-01-08T14:30:00Z"
}

Development

Project Structure

ai-usage-monitor/
├── src/
│   ├── providers/          # AI provider integrations
│   │   ├── base.ts        # Base provider class
│   │   ├── anthropic.ts    # Anthropic Claude
│   │   ├── openrouter.ts   # OpenRouter
│   │   ├── copilot.ts      # GitHub Copilot
│   │   ├── google.ts       # Google AI
│   │   ├── zai.ts         # Z.ai
│   │   ├── vercel.ts      # Vercel
│   │   └── index.ts       # Provider factory
│   ├── services/           # Business logic
│   │   ├── cache.ts       # Cache manager
│   │   └── aggregator.ts  # Data aggregator
│   ├── routes/             # API routes
│   │   └── api.ts        # API handlers
│   ├── types/              # TypeScript types
│   │   └── index.ts      # Type definitions
│   ├── utils/              # Utilities
│   │   ├── env.ts        # Environment loader
│   │   └── logger.ts     # Logger
│   └── server.ts           # Main server
├── public/                 # Static files
│   ├── index.html         # Dashboard HTML
│   ├── css/
│   │   └── styles.css     # Styles
│   └── js/
│       └── dashboard.js    # Dashboard JS
├── plans/                 # Architecture docs
│   ├── architecture.md     # System architecture
│   └── implementation-plan.md
├── package.json
├── tsconfig.json
├── bunfig.toml
├── .env.example
└── README.md

Adding a New Provider

Create a new provider file in src/providers/:

import { BaseProvider } from './base.js';
import { ProviderUsage } from '../types/index.js';

export class NewProvider extends BaseProvider {
  constructor(apiKey: string) {
    super({ apiKey, baseUrl: 'https://api.example.com' });
  }

  get id(): string {
    return 'newprovider';
  }

  get name(): string {
    return 'New Provider';
  }

  async fetchUsage(startDate: Date, endDate: Date): Promise<ProviderUsage> {
    // Implement API call and return usage data
  }
}

Export the provider in src/providers/index.ts:

export { NewProvider } from './newprovider.js';

Add the provider to the factory function:

if (env.newProviderApiKey) {
  providers.push(new NewProvider(env.newProviderApiKey));
}

Add environment variable to .env.example:

NEW_PROVIDER_API_KEY=your_key_here

Troubleshooting

Provider Not Showing Up

Ensure the API key is set in .env
Check the server logs for errors
Verify the API key is valid and has the required permissions

Dashboard Shows "Offline"

Check if the server is running
Verify the browser can connect to http://localhost:3000
Check browser console for JavaScript errors

High API Usage

Increase CACHE_TTL to cache data longer
Reduce the auto-refresh interval in public/js/dashboard.js
Disable auto-refresh by commenting out startAutoRefresh()

Build Fails

Ensure Bun is up to date: bun upgrade
Clear node_modules and reinstall: rm -rf node_modules && bun install
Check TypeScript errors: bun run tsc --noEmit

Performance

Startup Time: < 1 second
API Response Time: < 100ms (cached), < 2s (uncached)
Memory Usage: ~50MB (typical)
Binary Size: ~40MB (includes all dependencies)

Security

API keys are loaded from environment variables only
No API keys are logged or exposed in responses
CORS is configured for same-origin requests
Input validation on all API endpoints

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

Open an issue on GitHub
Check the documentation folder
Review the architecture plans

Acknowledgments

Dashboard design inspired by modern graphite themes
Built with Bun
Charts powered by Chart.js
Icons from Heroicons

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
data		data
docs		docs
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
PUBLISH.md		PUBLISH.md
README.md		README.md
WARP.md		WARP.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

AI Usage Monitor

Features

Quick Start

Prerequisites

Installation

Building for Production

Create a Single Binary

Run the Binary

Configuration

Environment Variables

Provider Setup

Anthropic Claude

OpenRouter

GitHub Copilot

Google AI (Gemini)

Z.ai

Vercel

Warp.dev (macOS only)

API Endpoints

GET /api/usage

GET /api/usage/:providerId

GET /api/health

GET /api/providers

Development

Project Structure

Adding a New Provider

Troubleshooting

Provider Not Showing Up

Dashboard Shows "Offline"

High API Usage

Build Fails

Performance

Security

License

Contributing

Support

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages