![\"Tokmon\"](\"site/public/icon.svg\"){kind=icon}
\n\n \n
\n Usage, cost, and rate-limit tracking for the coding tools on your machine.\n
\n\n\n ![\"npm\"](\"https://img.shields.io/npm/v/tokmon?style=flat-square&color=6caa71\")
![\"GitHub](\"https://img.shields.io/github/v/release/DavidIlie/tokmon?style=flat-square&color=7ccbcd\")
![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/DavidIlie/tokmon/ci.yml?style=flat-square&label=CI\")
![\"MIT](\"https://img.shields.io/badge/license-MIT-bd7bcd?style=flat-square\"){kind=icon}
\n Install ·\n Providers ·\n Docs ·\n Desktop downloads\n
\n\n\n\nTokmon collects the usage data your coding tools already keep locally, then\nshows it in a terminal dashboard, a local web app, and a desktop tray app. The\nthree clients use one local daemon, so their totals, account names, limits, and\nsettings stay in sync.\n\nIt currently understands Claude Code, Codex, Cursor, Copilot, opencode, pi,\nAntigravity, Gemini, and Grok.\n\n## Install\n\nRun the terminal dashboard without installing anything:\n\n```bash\nnpx tokmon\n```\n\nOr install the CLI globally:\n\n```bash\nnpm install -g tokmon\ntokmon\n```\n\nThe first run detects supported tools and lets you choose what to track. Node.js\n20 or newer is required; Node.js 24 or newer is recommended.\n\nFor the menu-bar/tray app, download the macOS, Windows, or Linux build from\n[GitHub Releases](https://github.com/DavidIlie/tokmon/releases). macOS builds are\nsigned and notarized. Windows builds are currently unsigned.\n\n## Three ways to use it\n\n| Surface | Best for | Start it |\n| --- | --- | --- |\n| Terminal | A fast overview while coding | `tokmon` |\n| Web dashboard | Charts, filtering, all-time history, and exports | `tokmon serve` |\n| Desktop | A customisable menu-bar summary and quick account details | Install from Releases |\n\nPin up to two providers directly from their desktop cards, then decide exactly\nwhat the macOS menu bar shows: provider marks, usage or today's tokens, optional\nprogress lines, and comfortable, compact, or tight spacing. Auto layout adapts\nto smaller displays; Custom mode exposes half-point edge and gap controls.\nClicking the item opens a compact view of every enabled provider and account,\nincluding usage, reset times, token totals, spend, cache savings, and recent\nhistory. The Desktop App settings can also launch Tokmon silently at login on\nmacOS and Windows, with native approval state shown in the app.\n\n\n\nThe web dashboard is bundled with the npm package and runs locally. It has\noverview, analytics, model, and history views with `7d`, `30d`, `90d`, `MTD`,\n`6M`, and all-time ranges.\n\n\n\n## Providers\n\nTokmon has two kinds of integrations. Usage providers expose local token and\ncost history; quota providers expose current plan limits or spend.\n\n### Usage and cost\n\n| Provider | Local source | Data shown |\n| --- | --- | --- |\n| Claude | `~/.claude/projects/**/*.jsonl` | Tokens, cost, cache savings, session/weekly/model limits |\n| Codex | `~/.codex/sessions/**/rollout-*.jsonl` | Tokens, cost, plan, session/weekly limits, credits |\n| Cursor | Cursor usage events and local composer data | Tokens, cost, plan, spend, on-demand caps |\n| opencode | `~/.local/share/opencode/opencode.db` | Tokens and the costs recorded by opencode |\n| pi | `~/.pi/agent/sessions/**/*.jsonl` | Tokens and the costs recorded by pi |\n| Grok | `~/.grok/logs/unified.jsonl` and session metadata | Tokens, cost, SuperGrok limits, credits |\n\n### Quota and billing\n\n| Provider | Data shown |\n| --- | --- |\n| Copilot | Plan, premium requests, and chat quota |\n| Antigravity | Plan and per-model-pool quota |\n| Gemini | Plan and Google Cloud Code quota |\n\nCached input is priced at each model's cache-read rate. It is not counted as\nfull-price input or treated as free. See [the provider guide](docs/providers.md)\nfor detection, multiple-account, and API details.\n\n## Useful commands\n\nThe CLI can query the same daemon without opening the interactive dashboard:\n\n```bash\ntokmon usage\ntokmon usage --period week --provider codex\ntokmon usage --model opus --json\ntokmon usage --period all --json --compact\ntokmon providers --json\ntokmon snapshot --refresh\ntokmon config get\n```\n\nJSON reports include a schema version, provider and account source IDs, model\ntoken/cost fields, and the local source paths behind each row. Start with\n[`docs/cli.md`](docs/cli.md) for filters and automation examples.\n\n## What is included\n\n- Daily, weekly, monthly, and all-time usage by provider, account, and model\n- Live quota bars with reset countdowns or exact reset dates\n- Burn rate, cache savings, token composition, and recent activity graphs\n- Multiple account homes, automatic discovery, and per-account opt-out\n- Shared privacy mode and themes across terminal, web, and desktop\n- Machine-readable CLI queries for scripts and coding agents\n- A local daemon that prevents every client from polling providers separately\n\n## Privacy\n\nTokmon is local-first and reads provider files without modifying them. SQLite\ndatabases are opened read-only. Credentials are used only to ask the provider's\nown API for your quota or billing data; tokens are never rendered or logged.\n\nThe daemon listens on loopback by default. LAN access is optional and clearly\nmarked unsafe in settings. See [privacy and security](docs/privacy-and-security.md)\nfor the exact files, network calls, and trust boundaries.\n\n## How It Works\n\nOne daemon owns collection, parsing, settings, and the stable RPC contract. The\nTUI, browser dashboard, desktop renderer, and CLI query commands are clients of\nthat contract. Whichever client starts first owns the daemon; compatible clients\nattach to it instead of starting another collector.\n\nLocal history is cached by file modification time and size, so repeat launches\ndo not parse every session again. Usage history and live billing refresh on\nseparate schedules. Development commands use a tagged daemon channel and cannot\ncollide with an installed release.\n\nThe architecture and daemon lifecycle are documented in\n[`docs/how-it-works.md`](docs/how-it-works.md).\n\n## Documentation\n\n| Guide | Covers |\n| --- | --- |\n| [Getting started](docs/getting-started.md) | Installation, first run, and requirements |\n| [Providers](docs/providers.md) | Sources, detection, accounts, billing, and limits |\n| [Terminal UI](docs/tui.md) | Views and keybindings |\n| [CLI queries](docs/cli.md) | `usage`, `providers`, `snapshot`, and JSON output |\n| [Web dashboard](docs/web-dashboard.md) | Local server, filters, exports, and LAN mode |\n| [Desktop app](docs/desktop.md) | Pins, popover, updates, and daemon attachment |\n| [Configuration](docs/configuration.md) | Settings, themes, discovery, accounts, and files |\n| [Privacy and security](docs/privacy-and-security.md) | Local data and network boundaries |\n| [How it works](docs/how-it-works.md) | Daemon, RPC contracts, caching, and client ownership |\n| [Development](docs/development.md) | Repository layout, checks, and development channels |\n| [Releasing](docs/releasing.md) | Tags, signing, artifacts, and package publication |\n\n## Development\n\n```bash\npnpm install\npnpm --prefix web install\npnpm --prefix site install\npnpm run check\npnpm run check:desktop\npnpm run check:site\npnpm run build\n```\n\nThis repository is a pnpm workspace for the published CLI and Electron app.\nThe web dashboard and marketing site have isolated lockfiles because they ship\nthrough different paths and should not enter the npm or Electron dependency\ngraphs. The layout is intentional; it is not a conventional `apps/*` monorepo.\n\nRead [the development guide](docs/development.md) before changing daemon\nownership, shared contracts, packaging paths, or release workflows.\n\n## Acknowledgements\n\nThe desktop interaction was researched against\n[OpenUsage](https://github.com/robinebers/openusage),\n[CodexBar](https://github.com/steipete/CodexBar), and\n[ccusage](https://github.com/ryoppippi/ccusage). Provider vector marks and\ncompact reset formatting adapted from OpenUsage are used under its MIT license.\nSee [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for details.\n\nTokmon is built with [Ink](https://github.com/vadimdemedes/ink), React,\nEffect, Astro, and Electron.\n\n## License\n\n[MIT](LICENSE) © [David Ilie](https://davidilie.com)\n","readmeFilename":"README.md"}