Tokenmeter is a free, open-source token usage and cost tracker for AI coding agents: Claude Code, OpenAI Codex CLI and GitHub Copilot CLI. It runs a local dashboard that shows how many tokens every prompt used, what it cost at API prices, how that compares with your Claude Pro, Claude Max or ChatGPT Plus plan, your cache hit rate and cache misses, and how close you are to your usage limits.

Use it for token monitoring and token optimization: watch token usage live, see which prompts, models and projects burn the most tokens, and find what to change to reduce token usage and lower your AI coding costs. It flags cache misses, where a long conversation loses its prompt cache and gets re-sent at full price, and splits every cost into cached, fresh and output tokens so the expensive part is obvious.

It reads the logs the agents already keep on your disk, so there is no API key, no proxy and no account, and nothing leaves your machine. Install it on macOS with Homebrew, or on Linux and Windows with pipx or uv. Zero dependencies: one Python file and one HTML file.

It answers questions like:

• How much does Claude Code cost me per day, per project or per prompt?
• How many tokens did Claude Code, Codex or Copilot use this week?
• Why did this prompt cost so much? Tokens are split into cached, fresh and output, with the math shown.
• Am I close to my Codex 5-hour or weekly limit, and how much have I used in the last 5 hours?
• How can I reduce Claude Code token usage? Start with the most expensive prompts and the cache misses.
• Which model or project is eating my token budget?
• Is my subscription worth it compared with API pricing?

Website and docs: tokenmeter.fyi

What you get

• Live feed of every model turn from Claude Code, Codex and GitHub Copilot CLI, updated a few seconds after each prompt finishes
• Spend tile that shows what you actually pay first (your subscription, prorated to the range) with the API-equivalent cost underneath, or the API cost on top if you have no plan configured
• Usage limits: Codex 5-hour and weekly windows as Codex reports them, plus rolling 5-hour and 7-day usage for every tool
• Active sessions with a context-fill gauge, so you see compaction coming
• Every prompt with its text, the turns it triggered, tokens, cost and duration, plus a resume command. Click any header to sort by date, tokens, cost, turns or duration
• Cache-miss detector: turns where the cached prefix collapsed and had to be re-written, with the prompt that was in progress and what the re-write cost
• Most expensive prompts, cost per git commit, cost mix by token type, and breakdowns by model, project and session
• Budget alerts: set a daily or monthly cap and get a desktop notification when you cross it
• Team mode: teammates export daily aggregates to one shared Tokenmeter and you filter by person
• Menu bar widget for SwiftBar or xbar showing today's spend
• Filters for time range, tool, project, model and user, kept in the URL so views are bookmarkable, plus CSV export and light and dark themes

How it works

Nothing is installed inside Claude Code, Codex or Copilot. All three already save every conversation to a log file on your disk, and each model reply in that log includes how many tokens it used. Tokenmeter just reads those logs.

1. Claude Code saves logs in ~/.claude/projects/, Codex in ~/.codex/sessions/, Copilot CLI in ~/.copilot/session-store.db.
2. server.py reads every log once, pulls out each prompt and each model reply with its token counts, and keeps them in memory.
3. It multiplies tokens by the prices in pricing.json to estimate cost.
4. It serves a web page at http://127.0.0.1:7788. The page asks the server every 4 seconds if anything changed and redraws when it has.

When you send a new prompt, the tool appends to its log, Tokenmeter notices the file grew, re-reads that one file, and the new turn shows up. Only your machine is involved. Nothing is sent anywhere.

The /tokenmeter skill is just a shortcut that starts server.py and gives you the link.

Install

Any machine with Python 3.9 or newer. Pick one:

brew install serkankorkut/tap/tokenmeter

pipx install tokenmeter-dashboard

uvx --from tokenmeter-dashboard tokenmeter --open

Or, as a Claude Code plugin straight from GitHub:

claude plugin marketplace add serkankorkut/tokenmeter
claude plugin install tokenmeter@tokenmeter

Or clone and link, which also installs the Codex skill and the tokenmeter command:

git clone https://github.com/serkankorkut/tokenmeter ~/repo/tokenmeter
~/repo/tokenmeter/install.sh

Then start it:

tokenmeter start

It runs in the background, opens http://127.0.0.1:7788, and starts again at login (a launchd agent on macOS, a systemd user service on Linux). tokenmeter stop stops it; plain tokenmeter runs it in the terminal instead. Inside Claude Code or Codex, /tokenmeter does the same.

Configuration

Create ~/.tokenmeter/config.json with only the keys you want to change. It is merged over the bundled pricing.json at startup, so upgrades never overwrite your settings. Example for someone on the $100 Claude plan and $20 ChatGPT Plus:

{"_plans": {"claude": 100, "codex": 20}, "_budget": {"daily": 30}}

Available keys:

Key	Purpose
model prefixes	USD per million tokens: input, cache_read, cache_write_5m, cache_write_1h, output. Anthropic and OpenAI list prices are included
_plans	What you pay per month per tool. Drives the Subscription spend tile. Default 0, which shows API-equivalent cost on top
_budget	daily and monthly caps in API-equivalent USD. Desktop notification once per period when exceeded
_context_windows	Context size by model prefix, for the context-fill gauge
_port	Port to use instead of 7788. Written for you by tokenmeter start --port N

Environment and flags:

Setting	Default	Purpose
--port N	7788	Listen port. With start it is saved as _port in ~/.tokenmeter/config.json, so the background service uses it too. Without a saved port, Tokenmeter tries 7788 and, if another app holds it, the next 10 ports
TOKENMETER_PORT		Port for this run only, overrides the saved one
--host	127.0.0.1	Bind address. Use 0.0.0.0 only for a team server
start, stop		Run in the background and open the browser; stop the background copy
--open		Open the browser after starting in the terminal
--user NAME	your login	Name shown in team mode
--export URL		Push your last 30 days to a team server every hour. Prompt text is never sent
TOKENMETER_TOKEN		Shared secret for team ingest, sent as X-Tokenmeter-Token
CLAUDE_CONFIG_DIR, CODEX_HOME, COPILOT_DB	~/.claude, ~/.codex, ~/.copilot/session-store.db	Where each tool keeps its logs
TOKENMETER_DIR	~/.tokenmeter	Where config.json, server.log and team data live

What "% of tokens" means

In the model, project and session tables it is that row's share of all tokens in the current filter. It always sums to 100 percent across a table.

Limits

Codex writes its 5-hour and weekly quota usage into every session log, so Tokenmeter shows the real percentages and reset times, as of the last Codex turn. Anthropic does not write Claude plan usage to disk. If a Claude Code OAuth token is present in the macOS keychain Tokenmeter queries the usage endpoint; otherwise it shows rolling 5-hour and 7-day totals from the logs.

Team mode

On a shared machine: tokenmeter --host 0.0.0.0 with TOKENMETER_TOKEN set. On each laptop: tokenmeter --export http://that-host:7788 with the same token. The shared dashboard gains a user filter. Only token counts, models, project paths and timestamps travel; prompt text stays local.

Menu bar

Copy menubar/tokenmeter.1m.sh into your SwiftBar or xbar plugin folder. It shows today's spend and, on click, the 5-hour and monthly numbers.

API

Endpoint	Returns
GET /api/usage	All records, prompts, and metadata as JSON
GET /api/version	Cheap change token, polled by the UI
GET /api/export.csv?since=ISO	CSV of records
GET /api/summary	Today, last 5 hours, month, projection, limits. Used by the menu bar widget
GET /api/commits	Recent commits per repo, for cost-per-commit
POST /api/ingest	Team mode receiver
GET /api/health	{"ok": true, "app": "tokenmeter"}

Development

python3 test_server.py
python3 -m tokenmeter --open

Release: bump the version in pyproject.toml, tokenmeter/server.py and .claude-plugin/plugin.json, tag vX.Y.Z and push. The GitHub Action publishes to PyPI via trusted publishing. Then run release/brew-formula.sh > ../homebrew-tap/Formula/tokenmeter.rb and push the tap: the script mirrors the sdist to a GitHub Release on the public tap repo and points the formula at it, so Homebrew installs are counted. release/brew-stats.sh prints those counts; PyPI downloads are at pypistats.org.

What shows where: the PyPI summary line is description in pyproject.toml, the PyPI long description is this README, the Homebrew one-liner is desc in release/brew-formula.sh, and the Claude Code plugin blurb is .claude-plugin/plugin.json. PyPI text only changes with a new release.

Roadmap

• Gemini CLI, Cursor agent and OpenCode parsers once their transcript formats are pinned down
• Slack or email weekly digest
• Windows notification support for budget alerts

License

MIT