TokenWatch Logo

TokenWatch

Self-hosted API quota & token limit tracker with live dashboard, 7-day history charts, and ntfy alerts.

๐Ÿ‡ฌ๐Ÿ‡ง English ยท ๐Ÿ‡ฉ๐Ÿ‡ช Deutsch

--- ## Overview **TokenWatch** is a self-hosted web application for monitoring AI API quotas and rate-limit windows across multiple providers in one dark-themed dashboard. It polls external provider APIs, accepts webhook pushes from a local Antigravity Language Server sync script, stores historical usage snapshots in PostgreSQL, displays interactive 7-day charts, and sends automated push alerts via **ntfy** when usage thresholds are reached. ### Architecture ```text +-----------------------------------+ POST /api/webhook/antigravity | Windows Host (Antigravity IDE) | -------------------------------------+ | Push-AntigravityQuota.ps1 | | | -> tokenwatch-sync.js | v +-----------------------------------+ +------------------------------+ | TokenWatch Server (Express) | +-----------------------------------+ REST API (30 min | Port 3000 | | External APIs | cron + live fetch) | - Static UI (public/) | | - POE (current_balance) | <-------------------> | - /api/quotas | | - MiniMax (coding_plan/remains) | | - /api/history | +-----------------------------------+ +--------------+---------------+ | +----------------------------+----------------------------+ v v +------------------------------+ +------------------------------+ | PostgreSQL Database | | ntfy Server | | - quotas (history) | | Alert threshold notifications| | - antigravity_latest (JSONB) | +------------------------------+ +------------------------------+ ``` --- ## Features - **Multi-Provider Quota Tracking**: - **POE**: Tracks remaining point balance against a `2,500,000` cap, daily refresh (`75,000`), expiring points, days until cap, points used today (calculated against the first UTC snapshot of the day), and a live UTC midnight refresh countdown. - **MiniMax**: Tracks `MiniMax (5h)` and `MiniMax (Weekly)` usage percentages (`model_name === 'general'`) with live reset countdowns. - **Antigravity (AG)**: Tracks 5 separate quota buckets via webhook push (`AG Gemini (5h)`, `AG Gemini (Weekly)`, `AG Claude (5h)`, `AG Claude (Weekly)`, `AG Gemini 4 Argon (Weekly)`), including individual reset timestamps (`Heute`, `Morgen`, or weekday + countdown). - **Persistent Antigravity State**: Incoming Antigravity webhook payloads are saved into the `antigravity_latest` PostgreSQL table (`JSONB`) and automatically restored on server startup. - **Automated Cron Snapshots & ntfy Alerts**: Every 30 minutes (`*/30 * * * *`), `node-cron` fetches all quotas, records them in PostgreSQL, and sends an `ntfy` notification (`Title: TokenWatch Alert`, `Tags: warning,robot`) when the configured threshold (`ALERT_THRESHOLD_PERCENT`, default `80`) is crossed. - **7-Day History Chart**: Interactive Chart.js line chart grouping snapshots into 5-minute intervals for `AG Gemini (5h)`, `AG Claude (5h)`, `POE`, and `MiniMax (5h)`. - **6 Selectable Progress Bar Themes**: Switch live between `Standard`, `Pac-Man`, `Battery`, `Nyan Cat`, `Matrix`, and `Lava` themes (also dynamically updates Chart.js dataset colors). - **Confetti Milestone**: Triggers a `canvas-confetti` celebration and displays `LIMIT REACHED!` (for non-POE providers) when a quota reaches `100%`. - **Windows Antigravity Sync & Debug Tools**: Includes `tokenwatch-sync.js`, `Push-AntigravityQuota.ps1` (Task Scheduler-ready), and cross-platform `fetch-quota.js` for inspecting raw local Language Server quota responses. --- ## How It Works & Tech Stack ### Internal Workflow 1. **Server Startup (`src/server.ts`)**: Initializes Express on `0.0.0.0:3000`, serves static assets from `public/`, initializes the PostgreSQL tables (`quotas` and `antigravity_latest`) via `initDb()`, and restores cached Antigravity quotas via `initAntigravityFromDb()`. 2. **Quota Polling (`src/services/providers.ts`)**: - `fetchPoeQuota()` queries `https://api.poe.com/usage/current_balance`. - `fetchMinimaxQuota()` queries `https://api.minimax.io/v1/api/openplatform/coding_plan/remains`. - `fetchAntigravityQuota()` reads the in-memory `antigravityCache` populated by `POST /api/webhook/antigravity` or restored from PostgreSQL. 3. **Alerting Logic (`src/cron.ts` & `src/services/ntfy.ts`)**: - For **POE** (where `percentage` represents *remaining* quota), an alert is triggered when `percentage <= (100 - ALERT_THRESHOLD_PERCENT)` (default `<= 20%` remaining). - For **MiniMax** and **Antigravity** (where `percentage` represents *used* quota), an alert is triggered when `percentage >= ALERT_THRESHOLD_PERCENT` (default `>= 80%` used). 4. **Local Antigravity Sync (`tokenwatch-sync.js`)**: Discovers running `language_server*` processes via PowerShell (`Get-CimInstance Win32_Process`), extracts `--csrf_token` and `--extension_server_port`, scans localhost listening ports (`Get-NetTCPConnection` with `netstat -ano` fallback), calls `POST /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary`, and forwards the parsed buckets to `/api/webhook/antigravity`. ### Tech Stack & Ports | Component | Technology / Version | Details | | :--- | :--- | :--- | | Runtime | Node.js 24 (`node:24-alpine`) | CommonJS TypeScript build (`tsc` -> `dist/`) | | Backend | Express `^5.2.1`, TypeScript `^7.0.2` | REST API + static file server | | Scheduler | `node-cron` `^4.6.0` | Runs every 30 minutes (`*/30 * * * *`) | | HTTP Client | `axios` `^1.20.0` | Provider API calls & ntfy alerts | | Database | PostgreSQL (`postgres:15-alpine`, `pg` `^8.23.0`) | Tables: `quotas`, `antigravity_latest` | | Frontend | Vanilla HTML/CSS/JS, Chart.js, `canvas-confetti` | Served from `public/` | | Default Port | `3000` (Container) / `3500` (Jannik-Cloud host bind) | Configurable via `PORT` | --- ## Prerequisites & Installation ### Prerequisites - **Local Development**: Node.js (v20+ / v24 recommended), npm, and a running PostgreSQL instance. - **Docker Deployment**: Docker and Docker Compose. - **Antigravity Local Sync (Optional)**: Windows host with Antigravity IDE running, Node.js, and PowerShell. ### Local Installation 1. Clone the repository: ```bash git clone https://git.orfel.de/Jannik/TokenWatch.git cd TokenWatch ``` 2. Install dependencies: ```bash npm install ``` 3. Create your environment file from `.env.example`: ```bash cp .env.example .env ``` Edit `.env` with your PostgreSQL credentials, `NTFY_URL`, and API keys. 4. Run in development mode (using `tsx`) or build for production: ```bash # Development npm run dev # Production build & start npm run build npm start ``` ### Docker Compose Setup Start TokenWatch together with PostgreSQL (`postgres:15-alpine`): ```bash cp .env.example .env # Edit .env with your credentials and API keys docker compose up -d ``` The dashboard will be available at `http://localhost:3000`. ### Jannik-Cloud Production Deployment A ready-to-use deployment template is provided in [`deployment-template/`](deployment-template/README.md): 1. Copy the contents of `deployment-template/` into `services/tokenwatch/` in your `Jannik-Cloud` repository. 2. Run `bash generate-env.sh` inside `services/tokenwatch/` to generate random PostgreSQL credentials and optionally encrypt `.env` to `.env.age` (using `keys/age-public-key.txt`). 3. Add your provider API keys (`POE_API_KEY`, `MINIMAX_API_KEY`, etc.) as needed. 4. The included `tokenwatch.caddy` configures reverse proxying for `tw.orfel.de`, `token.orfel.de`, and `tokenwatch.orfel.de` to `tokenwatch:3000`, while `docker-compose.yml` binds `127.0.0.1:3500:3000` on the external `jannik-cloud-net` network. 5. Note: `.github/workflows/docker.yml` also defines a GitHub Actions workflow that builds and pushes `ghcr.io//:latest` on pushes to `main` or `master`. --- ## Configuration ### Environment Variables (`.env.example`) | Variable | Description | Default / Example | | :--- | :--- | :--- | | `PORT` | HTTP server port | `3000` | | `DB_USER` | PostgreSQL username | `postgres` | | `DB_HOST` | PostgreSQL hostname | `postgres` | | `DB_NAME` | PostgreSQL database name | `tokenwatch` | | `DB_PASSWORD` | PostgreSQL password | `your_db_password` | | `DB_PORT` | PostgreSQL port | `5432` | | `NTFY_URL` | ntfy topic URL for threshold alerts | `https://ntfy.orfel.de/Token-Watch` (fallback in `ntfy.ts`: `https://ntfy.orfel.de/tokenwatch_dummy`) | | `ALERT_THRESHOLD_PERCENT` | Alert threshold percentage (`>=` used, or `<= 100 - N` remaining for POE) | `80` | | `POE_API_KEY` | Bearer token for `api.poe.com/usage/current_balance` | โ€” | | `MINIMAX_API_KEY` | Bearer token for `api.minimax.io/v1/api/openplatform/coding_plan/remains` | โ€” | | `ANTIGRAVITY_API_KEY` | Optional Antigravity key placeholder in `.env.example` / Compose | โ€” | | `ANTIGRAVITY_ENDPOINT` | Optional Antigravity endpoint placeholder in `.env.example` / Compose | `https://api.antigravity.google/v1/quota` | ### Docker Volumes - `pgdata:/var/lib/postgresql/data` โ€” Persists PostgreSQL `quotas` history and `antigravity_latest` state in `docker-compose.yml`. --- ## Usage ### Web Dashboard Open `http://localhost:3000` (or your configured reverse-proxy domain) to: - View real-time quota progress bars, reset times (`Heute`/`Morgen`/weekday), and countdowns for POE, Antigravity, and MiniMax. - Switch the **Progress Bar Style** dropdown between: 1. `Standard` 2. `Pac-Man` 3. `Battery` 4. `Nyan Cat` 5. `Matrix` 6. `Lava` - Inspect the 7-day usage trend in the **History** Chart.js graph. ### API Endpoints | Method | Endpoint | Description | | :--- | :--- | :--- | | `GET` | `/api/quotas` | Returns current quota objects for all providers, enriched with `meta.todayUsed` for POE. | | `GET` | `/api/history` | Returns the last 7 days of rows from the `quotas` PostgreSQL table ordered chronologically. | | `POST` | `/api/webhook/antigravity` | Updates the 5 Antigravity quota entries and persists them to `antigravity_latest`. | Example webhook payload accepted by `POST /api/webhook/antigravity`: ```json { "gemini_5h_remaining": 85, "gemini_weekly_remaining": 90, "claude_5h_remaining": 100, "claude_weekly_remaining": 75, "gemini_argon_weekly_remaining": 100, "gemini_5h_reset": "2026-01-01T15:00:00Z", "gemini_weekly_reset": "2026-01-07T00:00:00Z", "claude_5h_reset": null, "claude_weekly_reset": null, "gemini_argon_weekly_reset": null } ``` ### Antigravity Local Sync (Windows) 1. Verify `url` in `tokenwatch-sync.js` points to your TokenWatch instance (default: `https://tokenwatch.orfel.de/api/webhook/antigravity`). 2. Run manually: ```powershell .\Push-AntigravityQuota.ps1 ``` Or directly: ```bash node tokenwatch-sync.js ``` 3. **Windows Task Scheduler Automation**: - Trigger: Every 30 minutes - Action: Start a program - Program: `powershell` - Arguments: `-ExecutionPolicy Bypass -File "C:\GitHub\TokenWatch\Push-AntigravityQuota.ps1"` 4. **Debugging Raw Language Server Quotas**: ```bash node fetch-quota.js ``` Queries `/exa.language_server_pb.LanguageServerService/GetUserStatus` on the local Language Server (supports Windows, macOS, and Linux) and prints the complete JSON response. --- ## Project Structure ```text TokenWatch/ โ”œโ”€โ”€ .github/ โ”‚ โ””โ”€โ”€ workflows/ โ”‚ โ””โ”€โ”€ docker.yml # GitHub Actions Docker build & push to ghcr.io โ”œโ”€โ”€ deployment-template/ โ”‚ โ”œโ”€โ”€ README.md # Jannik-Cloud deployment guide โ”‚ โ”œโ”€โ”€ docker-compose.yml # Production Compose using jannik-cloud-net โ”‚ โ”œโ”€โ”€ generate-env.sh # Generates DB credentials & optional age encryption โ”‚ โ”œโ”€โ”€ service.enabled # Jannik-Cloud service activation marker โ”‚ โ””โ”€โ”€ tokenwatch.caddy # Caddy reverse proxy config โ”œโ”€โ”€ public/ โ”‚ โ”œโ”€โ”€ logos/ # Provider .ico assets โ”‚ โ”œโ”€โ”€ app.js # Frontend fetching, countdowns, Chart.js & theme switcher โ”‚ โ”œโ”€โ”€ favicon.png # TokenWatch logo & favicon โ”‚ โ”œโ”€โ”€ index.html # Dashboard HTML โ”‚ โ”œโ”€โ”€ logo-*.png / .ico / .svg # Provider icons (POE, Gemini, Claude, MiniMax, AG) โ”‚ โ””โ”€โ”€ style.css # Dark UI & 6 progress bar theme styles โ”œโ”€โ”€ src/ โ”‚ โ”œโ”€โ”€ services/ โ”‚ โ”‚ โ”œโ”€โ”€ db.ts # PostgreSQL pool, schema init, history & AG persistence โ”‚ โ”‚ โ”œโ”€โ”€ ntfy.ts # ntfy alert sender โ”‚ โ”‚ โ””โ”€โ”€ providers.ts # POE, MiniMax & Antigravity quota handlers โ”‚ โ”œโ”€โ”€ cron.ts # 30-minute quota logger & threshold alert job โ”‚ โ””โ”€โ”€ server.ts # Express app & REST API endpoints โ”œโ”€โ”€ .env.example # Example environment configuration โ”œโ”€โ”€ Dockerfile # Node 24 Alpine TypeScript build container โ”œโ”€โ”€ docker-compose.yml # Local/standalone Compose with PostgreSQL 15 โ”œโ”€โ”€ fetch-quota.js # Cross-platform Language Server quota debug script โ”œโ”€โ”€ language-server-process-utils.js# Process discovery & CLI arg extraction helpers โ”œโ”€โ”€ package.json # Dependencies and npm scripts โ”œโ”€โ”€ Push-AntigravityQuota.ps1 # Windows Task Scheduler wrapper script โ”œโ”€โ”€ tokenwatch-sync.js # Local Antigravity Language Server -> webhook sync โ””โ”€โ”€ tsconfig.json # TypeScript compiler configuration ``` --- ## License This project's own code and configuration are dedicated to the public domain under **CC0 1.0 Universal** โ€” see [`LICENSE`](LICENSE). External dependencies installed via package managers or Docker images retain their respective open-source licenses.