openusage

The coding agent usage dashboard you've been looking for.

Install · Providers · Config · Keybindings · Development

OpenUsage auto-detects AI coding tools and API keys on your workstation and shows live quota, usage, and cost data in your terminal. Zero config required — just run openusage.

Run it side-by-side with your coding agent:

OpenUsage running alongside OpenCode monitoring live OpenRouter usage.

Install

macOS (Homebrew, recommended)

brew install janekbaraniewski/tap/openusage

All platforms (quick install script)

curl -fsSL https://github.com/janekbaraniewski/openusage/releases/latest/download/install.sh | bash

From source (Go 1.25+)

go install github.com/janekbaraniewski/openusage/cmd/openusage@latest

Requires CGO (CGO_ENABLED=1). Pre-built binaries are also available on the Releases page.

Run

openusage

Auto-detection picks up local tools and common API key env vars. No config needed.

Features

• Zero config — auto-detects your AI tools and API keys, just run it
• Live dashboard — see spend, quotas, rate limits, and per-model usage at a glance
• 17 providers — covers coding agents (Claude Code, Cursor, Copilot, Codex, Gemini CLI), API platforms (OpenAI, Anthropic, OpenRouter, and more), and local tools (Ollama)
• Background tracking — collects data continuously, even when the dashboard is closed
• Deep cost insights — combine providers like OpenCode + OpenRouter for breakdowns by model, tool, and hosting provider
• Tool integrations — optional hooks for Claude Code, Codex CLI, and OpenCode provide richer, real-time usage data
• Customizable — 15+ built-in themes, adjustable time windows, configurable thresholds, provider reordering, plus external theme files

Supported providers

17 provider integrations covering coding agents, API platforms, and local tools. See docs/providers.md for all providers with detailed descriptions and screenshots.

Claude Code

Detection: claude binary + ~/.claude directory

Tracks daily activity, per-model token usage, 5-hour billing block computation, burn rate, and cost estimation.

OpenRouter

Detection: OPENROUTER_API_KEY environment variable

Tracks credits, activity, generation stats, and per-model breakdown across multiple API endpoints.

All providers

Coding agents & IDEs

API platforms

Configuration

No config file needed — auto-detection handles everything. Override or extend via:

• macOS/Linux: ~/.config/openusage/settings.json
• Windows: %APPDATA%\openusage\settings.json

{
  "auto_detect": true,
  "ui": { "refresh_interval_seconds": 30 },
  "accounts": [
    {
      "id": "openai-personal",
      "provider": "openai",
      "api_key_env": "OPENAI_API_KEY",
      "probe_model": "gpt-4.1-mini"
    }
  ]
}

Full reference: configs/example_settings.json

External themes

You can define custom themes as JSON files loaded at startup from:

• ~/.config/openusage/themes/*.json (macOS/Linux)
• %APPDATA%\\openusage\\themes\\*.json (Windows)
• Any extra directory in OPENUSAGE_THEME_DIR (path-list separated)

Theme files use the same color token fields as built-ins. See the full grayscale example:
configs/themes/grayscale.json

Additional example presets:

• Slate: configs/themes/slate.json
• Warm: configs/themes/warm.json

Daemon

Background data collection, even when the dashboard isn't open:

openusage telemetry daemon                # Run in foreground
openusage telemetry daemon install        # Install as system service (launchd / systemd)
openusage telemetry daemon status         # Check status
openusage telemetry daemon uninstall      # Uninstall

Manage tool integrations:

openusage integrations list [--all]       # List integration statuses
openusage integrations install <id>       # Install hook/plugin
openusage integrations uninstall <id>     # Remove

Keybindings

Development

make build    # Build binary to ./bin/openusage
make test     # Run tests with -race and coverage
make lint     # golangci-lint
make run      # go run cmd/openusage/main.go
make demo     # Preview with simulated data (no API keys needed)

Debug mode: OPENUSAGE_DEBUG=1 openusage

License

MIT