# OpenUsage

> Local-first terminal dashboard for AI tool spend, quotas, and rate limits across 19 providers — Claude Code, Codex CLI, Cursor, Copilot, OpenRouter, OpenAI, Anthropic, and more.

These docs cover installation, configuration, every provider integration, the optional background daemon, theming, the complete CLI and `settings.json` reference, troubleshooting, and contribution guidance.

Project home: https://openusage.sh
Source: https://github.com/janekbaraniewski/openusage
Full docs (machine-readable): /llms-full.txt

## OpenUsage docs

- [OpenUsage docs](https://openusage.sh/docs/): Local-first terminal dashboard for AI tool spend, quotas, and rate limits across 19 providers.

## Getting Started

- [First-run walkthrough](https://openusage.sh/docs/getting-started/first-run/): A tour of the OpenUsage dashboard on first launch, from auto-detection output to keybindings.
- [Install](https://openusage.sh/docs/getting-started/install/): Install OpenUsage on macOS, Linux, or Windows via Homebrew, script, or Go.
- [Quickstart](https://openusage.sh/docs/getting-started/quickstart/): Get OpenUsage running and see live data from your AI tools in under five minutes.
- [Uninstall](https://openusage.sh/docs/getting-started/uninstall/): Cleanly remove OpenUsage, its daemon, integrations, config, and data.
- [Upgrade](https://openusage.sh/docs/getting-started/upgrade/): Upgrade an existing OpenUsage install and refresh integrations.

## Concepts

- [Accounts](https://openusage.sh/docs/concepts/accounts/): The AccountConfig model, how api_key_env points to a variable name not a value, and how to track multiple accounts of the same provider.
- [Architecture](https://openusage.sh/docs/concepts/architecture/): How OpenUsage discovers tools, polls providers via the daemon, and renders snapshots in the TUI.
- [Auto-detection](https://openusage.sh/docs/concepts/auto-detection/): How OpenUsage discovers AI tools and API keys on first run, and how detected accounts merge with manual configuration.
- [Providers](https://openusage.sh/docs/concepts/providers/): What a provider is in OpenUsage, the three categories, and how each one shapes its own dashboard and detail widgets.
- [Snapshots](https://openusage.sh/docs/concepts/snapshots/): The UsageSnapshot data model, what metrics it carries, refresh cadence, and how time-window filtering works.
- [Telemetry pipeline](https://openusage.sh/docs/concepts/telemetry/): How the daemon stores events, deduplicates them, and turns them into snapshots — events, sources, dedup, and retention.
- [Themes](https://openusage.sh/docs/concepts/themes/): 18 bundled themes, how to cycle them, and where external theme files live.
- [Time windows](https://openusage.sh/docs/concepts/time-windows/): How OpenUsage filters aggregations by time, the difference between calendar 1d and rolling windows, and how retention bounds what you can query.

## Providers

- [Alibaba Cloud Model Studios](https://openusage.sh/docs/providers/alibaba-cloud/): Track Alibaba Cloud DashScope billing period, balance, spend, and per-model quotas in OpenUsage.
- [Amp](https://openusage.sh/docs/providers/amp/): Track Amp / AmpCode threads, credits, and per-model token usage in OpenUsage.
- [Anthropic](https://openusage.sh/docs/providers/anthropic/): Track Anthropic API rate limits in OpenUsage.
- [Claude Code](https://openusage.sh/docs/providers/claude-code/): Track Claude Code CLI sessions, billing blocks, burn rate, and per-model token usage in OpenUsage.
- [Codebuff](https://openusage.sh/docs/providers/codebuff/): Track local Codebuff (Manicode) chats, per-model tokens, and credit usage in OpenUsage.
- [Codex CLI](https://openusage.sh/docs/providers/codex/): Track OpenAI Codex CLI sessions, rate limits, and credit balance in OpenUsage.
- [GitHub Copilot](https://openusage.sh/docs/providers/copilot/): Track GitHub Copilot quotas, org seats, and rate limits in OpenUsage via the gh CLI.
- [Crush](https://openusage.sh/docs/providers/crush/): Track Crush coding-agent sessions, per-project usage, and model token counts in OpenUsage.
- [Cursor IDE](https://openusage.sh/docs/providers/cursor/): Track Cursor IDE plan spend, billing cycle, composer sessions, and per-model usage in OpenUsage.
- [DeepSeek](https://openusage.sh/docs/providers/deepseek/): Track DeepSeek balance breakdown and rate limits in OpenUsage.
- [Droid](https://openusage.sh/docs/providers/droid/): Track Factory Droid sessions and per-model token usage in OpenUsage.
- [Gemini API](https://openusage.sh/docs/providers/gemini-api/): Track Google Gemini API model catalog and per-model token limits in OpenUsage.
- [Gemini CLI](https://openusage.sh/docs/providers/gemini-cli/): Track Gemini CLI OAuth sessions, token usage, MCP config, and user quota in OpenUsage.
- [Goose](https://openusage.sh/docs/providers/goose/): Track Goose agent sessions, per-model token usage, and accumulated cost in OpenUsage.
- [Groq](https://openusage.sh/docs/providers/groq/): Track Groq API rate limits (RPM, TPM, RPD, TPD) in OpenUsage.
- [Hermes](https://openusage.sh/docs/providers/hermes/): Track Hermes Agent sessions, per-model token usage, and cost in OpenUsage.
- [Providers](https://openusage.sh/docs/providers/): Catalog of every AI tool and API platform OpenUsage tracks.
- [Kilo Code](https://openusage.sh/docs/providers/kilocode/): Track Kilo Code VS Code extension tasks, tokens, and cost in OpenUsage.
- [Kimi CLI](https://openusage.sh/docs/providers/kimi-cli/): Track local Kimi CLI sessions, per-model tokens, and cache usage in OpenUsage.
- [Kiro CLI](https://openusage.sh/docs/providers/kiro/): Track Kiro CLI (renamed Amazon Q Developer CLI) conversations and token estimates in OpenUsage.
- [Mistral AI](https://openusage.sh/docs/providers/mistral/): Track Mistral monthly budget, credit balance, spend, and tokens in OpenUsage.
- [Moonshot](https://openusage.sh/docs/providers/moonshot/): Track Moonshot organization, balance breakdown, quotas, and peak usage in OpenUsage.
- [Mux](https://openusage.sh/docs/providers/mux/): Track Mux per-workspace session usage, model spend, and tokens in OpenUsage.
- [Ollama](https://openusage.sh/docs/providers/ollama/): Track local Ollama models, VRAM, request log analytics, and cloud credits in OpenUsage.
- [OpenAI](https://openusage.sh/docs/providers/openai/): Track OpenAI API rate limits and quotas in OpenUsage.
- [OpenClaw](https://openusage.sh/docs/providers/openclaw/): Track local OpenClaw agent sessions, per-model tokens, and vendor-reported cost in OpenUsage.
- [OpenCode](https://openusage.sh/docs/providers/opencode/): Track OpenCode auth, available zen models, and spend via the telemetry plugin in OpenUsage.
- [OpenRouter](https://openusage.sh/docs/providers/openrouter/): Track OpenRouter credits, daily/weekly/monthly usage, generation analytics, and BYOK breakdown in OpenUsage.
- [Perplexity](https://openusage.sh/docs/providers/perplexity/): Track Perplexity Pro/Max usage in OpenUsage via browser-session auth.
- [Pi](https://openusage.sh/docs/providers/pi/): Track local Pi / Oh My Pi agent sessions, per-model tokens, and daily activity in OpenUsage.
- [Qwen CLI](https://openusage.sh/docs/providers/qwen-cli/): Track local Qwen CLI chat transcripts, per-model tokens, and reasoning usage in OpenUsage.
- [Roo Code](https://openusage.sh/docs/providers/roocode/): Track Roo Code VS Code extension tasks, tokens, and cost in OpenUsage.
- [xAI (Grok)](https://openusage.sh/docs/providers/xai/): Track xAI Grok credits, rate limits, and allowed models in OpenUsage.
- [Z.AI](https://openusage.sh/docs/providers/zai/): Track Z.AI 5-hour window, monthly usage, credit grants, and tool usage in OpenUsage.
- [Zed](https://openusage.sh/docs/providers/zed/): Track Zed Agent threads on the hosted zed.dev provider, with token totals and per-model breakdowns in OpenUsage.

## Daemon & Telemetry

- [Install the daemon](https://openusage.sh/docs/daemon/install/): Install, uninstall, and check the OpenUsage telemetry daemon on macOS launchd and Linux systemd-user.
- [Tool integrations](https://openusage.sh/docs/daemon/integrations/): Install hook integrations for Claude Code, Codex, and OpenCode so every turn is captured by the daemon.
- [Daemon overview](https://openusage.sh/docs/daemon/overview/): Background telemetry daemon that aggregates AI tool usage from collectors, hooks, and a disk spool into a single SQLite store.
- [Storage and retention](https://openusage.sh/docs/daemon/storage/): SQLite schema, deduplication strategy, provider links, spool, and retention controls for the OpenUsage daemon.
- [Daemon troubleshooting](https://openusage.sh/docs/daemon/troubleshooting/): Diagnose and fix daemon startup failures, socket errors, missing events, and database corruption.

## Customization

- [External themes](https://openusage.sh/docs/customization/external-themes/): Author custom OpenUsage themes as JSON files, where to put them, and the full color-token schema.
- [Keybindings](https://openusage.sh/docs/customization/keybindings/): Overview of how OpenUsage keybindings are organized by context, with a pointer to the full reference.
- [Themes](https://openusage.sh/docs/customization/themes/): All 18 bundled OpenUsage themes and how to switch between them from the TUI or settings.
- [Widget sections](https://openusage.sh/docs/customization/widgets/): Toggle, reorder, and hide-when-empty for dashboard tiles and detail widgets.

## Reference

- [CLI reference](https://openusage.sh/docs/reference/cli/): Every openusage command and subcommand with flags and behavior.
- [Configuration reference](https://openusage.sh/docs/reference/configuration/): Every field in OpenUsage's settings.json schema with type, default, and example values.
- [Environment variables](https://openusage.sh/docs/reference/env-vars/): Every environment variable OpenUsage reads, including per-provider API key envs.
- [Keybindings reference](https://openusage.sh/docs/reference/keybindings/): Complete keybinding reference for every OpenUsage TUI context.
- [Paths reference](https://openusage.sh/docs/reference/paths/): Every file and directory OpenUsage reads or writes, by operating system.

## Guides

- [Headless reports & statusline](https://openusage.sh/docs/guides/cli-reports/): Script usage and cost from the command line, and show a live status line in Claude Code.
- [Cost attribution](https://openusage.sh/docs/guides/cost-attribution/): Practical recipes for figuring out which tool, model, or project is burning your AI budget.
- [Headless servers](https://openusage.sh/docs/guides/headless-servers/): Running OpenUsage on a server without a desktop — daemon-only mode, tmux for the TUI, and SSH viewing.
- [Tracking multiple accounts](https://openusage.sh/docs/guides/multi-account/): How to monitor several accounts of the same provider — for example a personal and a work OpenAI key — side by side.
- [Multi-machine aggregation](https://openusage.sh/docs/guides/multi-machine/): Push usage snapshots from several workstations into a single hub and view the aggregated dashboard remotely.
- [Team tracking](https://openusage.sh/docs/guides/team-tracking/): Practical patterns for using OpenUsage to monitor a team's combined AI tool usage — and what's out of scope.
- [tmux integration](https://openusage.sh/docs/guides/tmux-integration/): A first-class tmux status bar for OpenUsage. Provider-agnostic, themed, configurable, and impossible to wedge.
- [Usage gauge projections](https://openusage.sh/docs/guides/usage-projections/): How OpenUsage computes the "resets in X · projected 100% in Y" annotation on windowed usage gauges, and when to trust it.

## Troubleshooting

- [Common issues](https://openusage.sh/docs/troubleshooting/common-issues/): The four issues most users hit, with fast diagnosis steps for each.
- [Daemon issues](https://openusage.sh/docs/troubleshooting/daemon-issues/): Diagnosing problems with the telemetry daemon — install failures, socket errors, log inspection, and SQLite recovery.
- [Debug mode](https://openusage.sh/docs/troubleshooting/debug-mode/): Turning on verbose logging and capturing a useful bug report.
- [Provider not detected](https://openusage.sh/docs/troubleshooting/provider-not-detected/): Per-detection-style checklists for finding why a provider isn't showing up in the dashboard.
- [\"Unmapped\" telemetry sources](https://openusage.sh/docs/troubleshooting/unmapped-telemetry/): A telemetry event is flowing in but has no tile. This page explains why and how to fix it with provider_links.

## Contributing

- [Adding a provider](https://openusage.sh/docs/contributing/add-provider/): High-level walk-through of the seven-phase process for contributing a new AI provider.
- [Development conventions](https://openusage.sh/docs/contributing/development/): Code style, branch & PR rules, and testing patterns used across OpenUsage.
- [Contributing](https://openusage.sh/docs/contributing/overview/): How OpenUsage is structured, the prerequisites, and the dev loop.

## More

- [FAQ](https://openusage.sh/docs/faq/): Frequently asked questions about OpenUsage — privacy, cost, platform support, accuracy, and how it compares to other tools.