Stop Guessing Your AI Quota! Track Everything with onWatch

Your Claude Code just hit a wall. Mid-refactor. Mid-thought. The cursor blinks mockingly while Anthropic's rate limiter laughs in 429. You've been there. We've all been there. That soul-crushing moment when your AI pair programmer goes silent—not because it's thinking, but because you've burned through your quota and had zero warning.

Here's the dirty secret the AI coding tool vendors don't want you to realize: they show you a snapshot. A single frame. "You've used 73% of your monthly limit." But what about your 5-hour sprint quota? Your 7-day rolling window? Your per-session burn rate when you're deep in a complex refactoring at 2 AM? Those gaps in visibility cost you momentum, money, and sanity.

Enter onWatch—the free, open-source AI API quota monitoring tool that developers are quietly installing to gain superhuman visibility into their AI spending. Not another SaaS dashboard that phones home. Not a browser extension scraping HTML. A lightweight background daemon written in Go, running locally, eating less than 50MB RAM, tracking nine major AI providers simultaneously with historical analytics that actually predict when you'll hit the wall.

If you're paying $3-$60/month for AI coding tools and flying blind on usage, this might be the most important repository you bookmark this year. Let's dive into why onWatch is becoming the secret weapon for developers who refuse to let quota surprises kill their flow state.

What is onWatch? The Missing FinOps Layer for AI Coding

onWatch is a free, open-source background monitoring daemon built by onllm.dev that tracks AI API quota consumption across Synthetic, Z.ai, Anthropic (Claude Code), Codex, GitHub Copilot, MiniMax, Gemini CLI, Cursor, and Antigravity—all in a unified, real-time dashboard.

Unlike the bare-bones usage pages your providers offer, onWatch fills the critical gap between "current usage snapshot" and the historical, per-cycle, cross-session view that developers actually need. It was born from a simple, painful observation: modern AI coding tools have sophisticated quota systems (rolling windows, tiered limits, OAuth token rotation), yet provide primitive visibility that leaves developers guessing.

The project is written in Go 1.25+, compiles to a single binary with zero runtime dependencies, and stores everything in local SQLite via a pure Go driver—no CGO, no external database server, no telemetry phoning home. The dashboard is built with Material Design 3, supports dark/light mode with system preference detection, and is fully PWA-installable for a native app experience.

What makes onWatch genuinely trend-worthy? It's GPL-3.0 licensed, has been mentioned in Awesome Go, and solves a problem that's exploding as AI coding tools proliferate. With providers like Anthropic implementing complex multi-tier quotas (5-Hour, 7-Day, 7-Day Sonnet, Monthly) and Codex adding OAuth-based authentication with automatic token refresh, developers need intelligence that adapts to these evolving systems. onWatch does exactly that—with automatic OAuth token refresh, rate limit bypass via token rotation, and multi-account support for providers like Codex and MiniMax.

Key Features That Separate onWatch from Basic Usage Pages

Real-Time Multi-Provider Polling Engine

At its core, onWatch runs parallel goroutine agents—one per configured provider—that poll quota APIs at configurable intervals (default 120s, range 10-3600s). Each agent is provider-aware, handling authentication nuances: Anthropic OAuth auto-detection from Claude Code credentials, Codex auth-state re-reading for token rotation, Cursor SQLite keychain extraction. All nine agents running simultaneously consume ~34MB idle, ~43MB under load—lighter than a single Chrome tab.

Historical Analytics & Predictive Intelligence

This is where onWatch destroys native dashboards. Every poll writes a timestamped snapshot to SQLite with WAL mode for concurrency. The dashboard renders Chart.js time-series area charts showing quota utilization percentages across configurable ranges (1h, 6h, 24h, 7d, 30d). But the real magic is insights: burn rate forecasting with linear regression, billing-period averages, usage variance calculation, trend detection with threshold crossing alerts, and cross-quota ratio analysis like "1% weekly consumption ≈ 24% of 5-hour sprint capacity."

Cycle-Aware Reset Tracking

Different providers use different reset mechanics—monthly billing, 5-hour rolling windows, 24-hour cycles. onWatch detects and tracks each provider's reset cycle independently, showing live countdown timers to next reset and per-cycle consumption statistics. The Cycle Overview correlates cross-quota peak usage points, revealing which quotas spike together—critical for understanding burst patterns.

Session-Based Attribution

Every agent run creates a session tracking peak consumption. Compare your Monday morning deep-work session against Friday's scattered code reviews. For researchers and grant-funded developers, this enables per-session API cost attribution for reports and methodology documentation.

Enterprise-Grade Notifications

Configure SMTP email alerts (AES-GCM encrypted passwords at rest) and browser push notifications via Web Push Protocol (VAPID) with zero external dependencies. Set per-quota threshold overrides—warning at 60%, critical at 85%—with independent delivery channel selection per alert type.

Prometheus Metrics Endpoint (Beta)

Expose /metrics with optional bearer token protection for integration with your existing monitoring stack. Grafana dashboards, Alertmanager rules, PagerDuty escalation—onWatch speaks your infrastructure's language.

Use Cases: Where onWatch Transforms Your Workflow

The Solo Developer Battling Budget Anxiety

You're a freelancer with Claude Code ($20/month), GitHub Copilot ($10/month), and a Synthetic subscription. Three dashboards, three login flows, three different "usage" definitions. onWatch unifies them with side-by-side quota cards showing utilization percentages, live reset countdowns, and consumption rates. When your Anthropic 5-hour sprint hits 80%, you get a push notification—time to switch to Copilot for the next two hours, or pace your requests. No more surprise throttling during client demos.

The Small Team with Shared API Keys

Three developers sharing a single Anthropic organization key. Classic nightmare: who burned through the monthly quota in week two? onWatch's session tracking and historical export via SQLite let you attribute usage to time periods (if not individual users—yet). Combined with cycle history, you can budget next month's API spend with data instead of guesswork. The shared dashboard at http://team-server:9211 becomes your team's FinOps command center.

The DevOps Engineer Shadow-AI-Governance

Your engineering org has "approved" AI tools, but developers are sneaking in personal API keys, company credit cards, and unvetted providers. onWatch deployed as a lightweight sidecar (<50MB) on developer workstations or a central server ingesting API Integrations telemetry gives you visibility without blocking productivity. The Prometheus endpoint feeds your existing Grafana, and the zero-telemetry GPL-3.0 source passes security review.

The Privacy-Conscious Regulated Industry Developer

Healthcare. Finance. Government. You cannot use SaaS analytics that exfiltrate usage patterns to third parties. onWatch is fully air-gappable: single binary, local SQLite, no network calls except to configured provider APIs. The source is auditable on GitHub. SMTP passwords encrypted with AES-256-GCM. Session cookies with secure flags. This is monitoring that satisfies compliance officers.

The Researcher Grant-Tracking API Costs

Your NSF grant requires per-experiment cost attribution. Your IRB wants to know exactly which AI models processed which participant data. onWatch's per-session peak consumption tracking and SQLite export give you timestamped, auditable records. The API Integrations feature even lets you instrument your custom pipelines for complete coverage.

Step-by-Step Installation & Setup Guide

macOS & Linux: One-Line Install

The fastest path to quota enlightenment:

# Automatic installation: downloads binary, creates .env, sets up service
curl -fsSL https://raw.githubusercontent.com/onllm-dev/onwatch/main/install.sh | bash

This installs to ~/.onwatch/, creates a .env configuration file, sets up a systemd user service (Linux) or self-daemonizes (macOS), and adds onwatch to your PATH. The macOS build includes menubar support.

Homebrew (macOS & Linux)

brew install onllm-dev/tap/onwatch
onwatch setup    # Interactive wizard for API keys and configuration

Windows: PowerShell One-Liner

# Downloads binary, runs interactive setup, configures PATH
irm https://raw.githubusercontent.com/onllm-dev/onwatch/main/install.ps1 | iex

Or download install.bat from Releases for offline installation.

Docker Deployment (Recommended for Servers)

# Clone and configure
git clone https://github.com/onllm-dev/onwatch.git && cd onwatch
cp .env.docker.example .env
nano .env  # Add your API keys

# Start with Docker Compose (includes memory limits, log rotation)
docker-compose up -d

The distroless image is ~10-12 MB; Alpine variant with shell access is ~15 MB. The container runs as non-root (UID 65532) with data persisted via volume mount at /data.

Manual Build from Source (Go 1.25+)

git clone https://github.com/onllm-dev/onwatch.git && cd onwatch
cp .env.example .env    # Edit with your API keys
./app.sh --build && ./onwatch --debug    # Or: make build && ./onwatch --debug

Essential Configuration

Edit ~/.onwatch/.env (or .env in project directory):

# At least one provider required; configure any combination for parallel tracking
SYNTHETIC_API_KEY=syn_your_key_here       # https://synthetic.new/settings/api
ZAI_API_KEY=your_zai_key_here             # https://www.z.ai/api-keys
ANTHROPIC_TOKEN=your_token_here           # Auto-detected from Claude Code credentials
CODEX_TOKEN=your_token_here               # From ~/.codex/auth.json
COPILOT_TOKEN=ghp_your_token_here         # GitHub PAT with copilot scope
MINIMAX_API_KEY=your_key_here             # https://platform.minimax.io

# Dashboard authentication (change from defaults!)
ONWATCH_ADMIN_USER=admin
ONWATCH_ADMIN_PASS=changeme

Pro tip: Anthropic tokens are auto-detected from macOS Keychain, Linux keyring, or ~/.claude/.credentials.json. Codex tokens are re-read at runtime from ~/.codex/auth.json—rotation is automatic. Cursor credentials extract from Cursor Desktop's SQLite or system keychain.

Start, Stop, and Verify

onwatch              # Background daemon (logs to ~/.onwatch/data/.onwatch.log)
onwatch --debug      # Foreground mode with stdout logging (great for troubleshooting)
onwatch stop         # Graceful shutdown
onwatch status       # Check daemon state

Open http://localhost:9211 and authenticate with your .env credentials.

REAL Code Examples from the onWatch Repository

Let's examine actual implementation patterns from onWatch's codebase and documentation—understanding how this tool achieves its remarkable efficiency and provider flexibility.

Example 1: The Core Architecture — Parallel Agent Goroutines

onWatch's architecture diagram from the README reveals its elegant concurrency model:

                              ┌──────────────┐
                              │  Dashboard   │
                              │  :9211       │
                              └──────┬───────┘
                              ┌──────┴───────┐
                              │   SQLite     │
                              │   (WAL)      │
                              └──┬──┬──┬──┬──┬──┬──┬──┬─┘
       ┌───────────────────────┘  │  │  │  │  │  │  └───────────────────────┐
  ┌────┴─────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴─────┐
  │ Synthetic│ │  Z.ai   │ │Anthropic│ │  Codex  │ │ Copilot │ │ MiniMax │ │Antigrav. │
  │  Agent   │ │  Agent  │ │  Agent  │ │  Agent  │ │  Agent  │ │  Agent  │ │  Agent   │
  └────┬─────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬─────┘
  ┌────┴─────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴─────┐
  │ Synthetic│ │  Z.ai   │ │Anthropic│ │chatgpt  │ │ GitHub  │ │ MiniMax │ │ Local    │
  │  API     │ │  API    │ │OAuth API│ │OAuth API│ │Copilot  │ │  API    │ │ RPC      │
  └──────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘

What's happening here: Each provider agent runs as an independent goroutine, polling its respective API at the configured interval. They write to a shared SQLite database using WAL (Write-Ahead Logging) mode, which enables concurrent reads without blocking writes. The HTTP dashboard server reads from this same SQLite instance. This design eliminates complex message queues or in-memory caches—simplicity that contributes to the <50MB memory footprint.

The key insight: no central orchestrator bottleneck. If Anthropic's API is slow, it doesn't block Z.ai polling. If one provider's OAuth token expires, only that agent retries while others continue.

Example 2: Docker Deployment with Proper Non-Root Permissions

From the README's Docker section, here's the production deployment pattern with security-conscious volume handling:

# Pre-create data directory with correct ownership for non-root container (UID 65532)
mkdir -p ./onwatch-data && sudo chown -R 65532:65532 ./onwatch-data

# Run distroless image (~10-12 MB, no shell access for minimal attack surface)
docker run -d --name onwatch -p 9211:9211 \
  -v ./onwatch-data:/data \
  -e SYNTHETIC_API_KEY=your_key_here \
  ghcr.io/onllm-dev/onwatch:latest

Critical security detail: The container runs as UID 65532 (distroless default non-root user). Without the chown, SQLite database creation fails with permission denied. The docker-compose.yml includes 64MB memory limit, 32MB reservation, 10MB log rotation with 3 backups, and unless-stopped restart policy—production-hardened defaults.

For debugging scenarios (like Codex multi-account setup requiring interactive configuration):

# Alpine variant with shell access (~15 MB, includes /bin/sh)
docker run -d --name onwatch -p 9211:9211 \
  -v onwatch-data:/data \
  -e SYNTHETIC_API_KEY=your_key_here \
  ghcr.io/onllm-dev/onwatch:alpine

Example 3: Self-Update Mechanism with Systemd Integration

onWatch's self-update capability demonstrates sophisticated process management for a Go binary:

# Check for updates and self-update from CLI
onwatch update

Under the hood, this triggers a carefully orchestrated replacement. For systemd deployments, onWatch detects its service via /proc/self/cgroup, validates the unit file's Restart=always setting, runs systemctl daemon-reload, and triggers systemctl restart for clean lifecycle management. For standalone mode (macOS or non-systemd Linux), it spawns the new binary which takes over via PID file atomically. If spawn fails, it falls back to systemctl restart as safety net.

The downloaded binary is validated by checking executable magic bytes (ELF for Linux, Mach-O for macOS, PE for Windows) before replacement—preventing corruption from partial downloads.

Example 4: Custom API Integrations for Local Telemetry

For workflows not covered by built-in providers, onWatch accepts normalized JSONL events:

# Your custom API wrapper appends events to this directory
~/.onwatch/api-integrations/

# Example JSONL event format (normalized schema):
# {"timestamp":"2025-01-15T09:23:47Z","provider":"custom-llm","model":"gpt-custom","tokens_input":1247,"tokens_output":89,"cost_usd":0.0034}

The daemon tails these files automatically when ONWATCH_API_INTEGRATIONS_ENABLED=true (default). Data persists with configurable retention (ONWATCH_API_INTEGRATIONS_RETENTION=1440h default = 60 days; set 0 to disable pruning). This enables unified monitoring of external API calls, internal microservices, or experimental models alongside commercial providers.

Example 5: Environment Configuration for Multi-Account Codex

A sophisticated configuration pattern from the CLI reference:

# .env configuration for Codex with multi-account support (Beta)
CODEX_TOKEN=your_primary_token_here    # Recommended for Codex-only setups

# During runtime, onWatch re-reads from:
# ~/.codex/auth.json (or $CODEX_HOME/auth.json)
# This enables automatic token rotation without restart

The runtime re-reading is crucial: when OpenAI refreshes OAuth tokens (every ~2 hours), onWatch picks up the new access_token automatically. For multi-account tracking (Beta), add additional ChatGPT accounts via the dashboard UI—each polls independently with separate auth state, enabling agency teams to monitor personal vs. organization usage.

Advanced Usage & Best Practices

Optimize Polling Intervals for Your Workflow

Default 120s is conservative. For intensive coding sessions, reduce to 60s (ONWATCH_POLL_INTERVAL=60 or --interval 60). For background monitoring, increase to 300s. Anthropic's aggressive rate limits (~5 requests/token) make automatic token refresh essential—onWatch handles this transparently, but manual polling faster than 60s risks 429s even with bypass.

Leverage Session Tracking for Productivity Analysis

Export SQLite data directly: sqlite3 ~/.onwatch/data/onwatch.db "SELECT * FROM sessions WHERE peak_tokens > 10000 ORDER BY started_at DESC LIMIT 10;". Identify your highest-intensity coding periods. Correlate with git commits to understand which tasks burn most quota.

Menubar for macOS: Glanceable Awareness

Enable in Settings > Menubar. The Detailed view with sparkline trends keeps quota awareness peripheral—no context switching to browser. Configure provider ordering by drag-and-drop to prioritize your most constrained quotas.

API Integrations for Complete Coverage

Instrument your CI/CD pipelines, data processing scripts, or custom LLM proxies. The normalized JSONL schema ensures consistent analytics across heterogeneous infrastructure. Set aggressive retention pruning (ONWATCH_API_INTEGRATIONS_RETENTION=168h for 7 days) for high-volume ingestion to control database growth.

Backup Your SQLite Database

The WAL mode database at ~/.onwatch/data/onwatch.db contains valuable historical data. Include in your regular backups, or set ONWATCH_DB_PATH to a cloud-synced directory (with appropriate security for API keys in .env).

Comparison with Alternatives

The verdict: Native dashboards are free but fragmented. SaaS analytics are powerful but expensive and require trusting third parties with your usage patterns. Custom scripts are flexible but become maintenance nightmares. onWatch occupies the sweet spot: free, local, unified, with enterprise features like Prometheus export and email alerts.

FAQ: Common Developer Concerns

Does onWatch work with my AI coding tool?

Yes—if it uses supported APIs. onWatch monitors providers, not tools. Cline, Roo Code, Kilo Code, Claude Code, Codex CLI, Cursor, GitHub Copilot, MiniMax Coding Plan, Antigravity, and any custom tool using Synthetic, Z.ai, Anthropic, Codex, Copilot, MiniMax, Gemini CLI, Cursor, or Antigravity keys are tracked automatically.

How does onWatch handle Anthropic's aggressive rate limits?

onWatch implements automatic rate limit bypass via OAuth token rotation. When Anthropic's /api/oauth/usage endpoint returns 429 (~5 requests/token limit), onWatch refreshes the OAuth token, obtaining a fresh rate limit window. This requires OAuth credentials (auto-detected from Claude Code); API key authentication doesn't support refresh. Log shows "Rate limit bypassed successfully."

Can I run onWatch completely offline?

Partially. The daemon itself requires no internet for dashboard or SQLite operations. Provider agents need outbound HTTPS to their respective APIs. For fully air-gapped environments, use API Integrations with local JSONL ingestion from your own infrastructure.

Is my API key secure?

Keys load from .env (never committed), are redacted in all log output, and never transmitted anywhere except to configured provider APIs. The dashboard uses session-based auth with cookie + Basic Auth fallback. Passwords stored as SHA-256 with constant-time comparison. SMTP passwords encrypted with AES-256-GCM.

How do I migrate data between machines?

Copy ~/.onwatch/data/onwatch.db and ~/.onwatch/.env (securely!). The SQLite database is portable across platforms. On first run, onWatch auto-migrates legacy ./onwatch.db to the new path.

What's the catch? How is this free?

No catch. GPL-3.0 licensed, developed by onllm.dev with community contributions. Consider buying the maintainer a coffee or starring the repository to help others discover it.

Can I contribute or request features?

Absolutely. Fork, create feature branches (feat/my-feature), write tests first, run ./app.sh --test, and open PRs with conventional commit format. The project is in active Beta—features and APIs evolve with community input.

Conclusion: Take Back Control of Your AI Quotas

The AI coding revolution has a hidden tax: cognitive load from quota anxiety. Every time you hesitate before sending a complex prompt, every 2 AM throttling surprise, every budget meeting where you can't explain last month's API spend—that's friction killing your flow.

onWatch eliminates this friction with elegant, local-first engineering. A single Go binary. SQLite history that persists across sessions. Predictive analytics that warn before you hit walls. Nine providers unified in one Material Design 3 dashboard. All under 50MB RAM, zero telemetry, GPL-3.0 auditable source.

Whether you're a solo developer optimizing a $20 Claude Code subscription, a team lead governing shadow AI usage, or a researcher documenting grant expenditures, onWatch provides the visibility layer that should have shipped with every AI coding tool.

The installation is one line. The dashboard is at localhost:9211. Your future self—the one coding at 2 AM without interruption—will thank you.

Star onWatch on GitHub, install it today, and never guess your quota again.