{ "markdown": "

\n \"Token\n

\n\n# Token Meter\n\n> Track Claude Code, Codex & Cursor token usage and cost locally — no account, no cloud.\n>\n> One local dashboard for your **Claude Code** and **Codex** token usage.\n> Free, MCP-aware, MIT-licensed core.\n>\n> npm: [`@whdrnr2583/token-meter`](https://www.npmjs.com/package/@whdrnr2583/token-meter) · GitHub: [`whdrnr2583-cmd/token-meter`](https://github.com/whdrnr2583-cmd/token-meter) · Site: [token-meter.dev](https://token-meter.dev)\n\nToken Meter parses the JSONL files that Claude Code and Codex already write to\ndisk and turns them into a real dashboard: cost per project, per model, per MCP\ntool, per hour. Your data never leaves your machine.\n\n## Run your first audit\n\n```sh\nnpx -y @whdrnr2583/token-meter audit\n```\n\nScans your ingested Claude Code + Codex history for expensive sessions,\noversized tool responses, slow tools, repeated calls, and cache waste, ranked\nby cost and confidence. Runs entirely against your local SQLite database —\nsame local-first, no-cloud processing as the rest of Token Meter. Add\n`--json` for machine-readable output; see [docs/audit.md](docs/audit.md) for\nthe full flag list and JSON schema.\n\n## When to use this\n\nUse Token Meter if you:\n\n- want to know how many tokens and dollars your Claude Code or Codex sessions are costing — broken down by project, model, and MCP tool\n- are on a flat-fee plan (Claude Max, etc.) and want to see what the equivalent API cost would be\n- want to find which MCP server or tool is eating the most tokens, or which hour of the day is most expensive\n- want to resume a recent session and need the `claude --resume` / `codex resume` command handy\n- want all of the above offline, with no account and nothing uploaded\n\nNot a fit if you need billing-grade numbers validated against your Anthropic or OpenAI invoice — Token Meter computes estimates from local JSONL files only.\n\n## MCP tools\n\nWhen Token Meter is wired as an MCP server (`install-mcp all`), four tools become available to your AI assistant:\n\n| Tool | What it returns |\n|---|---|\n| `usage_summary` | Daily table of token counts, USD-equivalent cost, and call counts — broken down by day and model |\n| `recent_sessions` | Latest sessions with paste-ready `claude --resume` / `codex resume` commands |\n| `session_tools` | Per-tool breakdown inside a session: call count, total tokens, average latency, response size |\n| `refresh_data` | Re-scans your local JSONL logs for new activity, then returns a fresh summary |\n\nAll four are read-only. No data leaves your machine.\n\n## Example prompts\n\nCopy-paste any of these into Claude Code or Cursor after installing the MCP server:\n\n```\nShow me my token usage and cost for the last 7 days.\n```\n```\nList my recent sessions so I can pick one to resume.\n```\n```\nShow the tool breakdown for my most recent session — which tool used the most tokens?\n```\n```\nRefresh token-meter data, then tell me which model cost the most this week.\n```\n```\nWhich hour of the day am I spending the most tokens on?\n```\n\n## Quick start\n\n```sh\nnpx @whdrnr2583/token-meter ingest # scan ~/.claude/projects + ~/.codex/sessions\nnpx @whdrnr2583/token-meter stats 30 # CLI summary for last 30 days\nnpx @whdrnr2583/token-meter serve # http://localhost:8765 dashboard\nnpx @whdrnr2583/token-meter mcp # run as an MCP server for Claude Code / Cursor\n```\n\n> The package is published under an npm scope (`@whdrnr2583/`) because the\n> bare `token-meter` name collides with an existing similar name on npm. The\n> CLI binary is still called `token-meter` after install.\n\n### Connect Token Meter to your AI tool (MCP)\n\nOne command registers Token Meter with every supported client on your machine:\n\n```sh\nnpx -y @whdrnr2583/token-meter install-mcp all\n```\n\nHandles Claude Code, Cursor, and Claude Desktop — idempotent, backs up existing\nconfig, preserves other MCP servers. Single-client variants:\n`install-mcp claude-code | cursor | claude-desktop`. Add `--dry-run` to preview.\n\n> **Or have your LLM do it.** Open Claude Code / Cursor / Claude Desktop and ask:\n> *\"Read https://raw.githubusercontent.com/whdrnr2583-cmd/token-meter/main/docs/mcp-server.md\n> and set up token-meter as my MCP server.\"*\n\nManual one-liners (if you'd rather not run our installer):\n\n| Client | Command / config |\n|---|---|\n| **Claude Code** | `claude mcp add token-meter -- npx -y @whdrnr2583/token-meter mcp` then `claude mcp list` to verify |\n| **Cursor** | Edit `~/.cursor/mcp.json` (Windows: `%USERPROFILE%\\.cursor\\mcp.json`) — see [docs/mcp-server.md](docs/mcp-server.md#cursor) |\n| **Claude Desktop** | Edit `claude_desktop_config.json` — see [docs/mcp-server.md](docs/mcp-server.md#claude-desktop) |\n| **ChatGPT** | Stdio-only for now; HTTP wrapper recipe in [docs/mcp-server.md](docs/mcp-server.md#chatgpt-custom-connector--apps) |\n| **Other (Continue, Zed, custom)** | `npx -y @whdrnr2583/token-meter mcp` over stdio |\n\nThen ask: *\"Use token-meter to show my recent sessions\"* or *\"Use token-meter usage_summary for this week\"*.\n\n> **Claude Code shortcut:** run `npx -y @whdrnr2583/token-meter install-command claude-code` once to register the `/token-meter` slash command. After reopening your session, type `/token-meter` for a one-shot summary without natural language.\n\nFull setup + verification + troubleshooting: **[docs/mcp-server.md](docs/mcp-server.md)**.\n\nStorage: `~/.tokenpulse/usage.db` (SQLite). Remove the folder to start over.\nThe folder name will become `~/.tokenmeter/` in a future release with an\nautomatic migration; until then the v0.1 directory keeps its original name.\n\n## What you see\n\n- **USD-equivalent cost** per day, model, project. Useful if you're on a Max\n plan and want to know what the API would have cost.\n- **MCP and tool breakdown**: which MCP server is eating tokens, how slow each\n tool is on average, response sizes per call.\n- **Hourly distribution** of output tokens.\n- **Claude Code + Codex side-by-side**, in one view.\n\n### A note on the dollar figures\n\nCosts are **estimates** computed locally from the token counts that Claude\nCode and Codex already write to their JSONL files, multiplied by the model's\npublished per-million-token rate. They are **not** validated against your\nactual Anthropic / OpenAI invoice and may diverge for several reasons:\n\n- Vendors change pricing; the table in `src/pricing.ts` is a snapshot\n- Subscription plans (Pro / Max) bill a flat fee — the on-screen $ is what\n the API would have cost, not what you pay\n- Some token categories (server-side tool use, cache write variants) are\n approximated\n\nTreat the numbers as **relative signal** for spotting waste, not as\nbilling-grade accounting. Token Meter ships a regression test that the\ncalculation is reproducible, and an audit script that checks invariants;\nneither verifies the rates against vendor invoices.\n\n## Why local-first\n\n- Your JSONL contains source code, prompts, and tool results. Token Meter never\n uploads any of it. Heuristics, regex, and SQL aggregation only.\n- No SDK to integrate, no proxy to configure for the free tier.\n- The CLI and dashboard core are **MIT licensed**.\n\n## Pricing\n\n| Tier | Price | What you get |\n|---|---|---|\n| **Free** | $0 | Claude Code + Codex parsing, MCP/tool breakdown, hourly/model/project breakdown, 7-day history, 1 desktop alert |\n| **Pro** | **$5/mo** | Everything in Free, reframed as a monthly spend review: 30-day history (this month vs last), per-session/per-message drill-down to the run that blew the budget, cache-efficiency dollars saved, waste signals (oversized tool responses + cache that didn't pay off), plus unlimited smart alerts (desktop + webhook) |\n| Pro+ | _later_ | Local LLM proxy (Ollama / LM Studio / llama.cpp / vLLM), GPU/VRAM tracking, auto actions |\n\nPro is the difference between glancing at last week's number and reviewing where the month's spend leaked. Pro is live — [Subscribe at token-meter.dev](https://token-meter.dev#pricing).\n\nPro+ ships once Pro sign-ups + community demand confirm the segment.\n\n## Roadmap\n\n- **M1** ✅ Claude Code parsing, MCP/tool breakdown, hourly stats\n- **M2** ✅ Codex integration\n- **M3** Pro tier ($5), Polar.sh billing, license activation\n- **M4+** Pro+ (local LLM proxy, GPU tracking), conditional on demand\n\n## Privacy & security\n\n- Tokens are counted from the JSONL files Claude Code and Codex already write.\n Token Meter does not touch network APIs of either vendor.\n- No prompt or response bodies are stored by default — only metadata\n (timestamps, token counts, tool names, response lengths).\n- The database lives under `~/.tokenpulse/`; delete it to wipe. (Renamed to\n `~/.tokenmeter/` in a future release with an automatic migration.)\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for release notes and breaking changes.\n\n## License\n\nMIT for the CLI, dashboard, and parsers. Pro-tier features ship in a separate\npackage under a closed source license.\n", "bytes": 9054, "sha": "1821d424a343bc77265bc0bef9c8291901bd2d67a74f156fc776c8b17dfbb3f1", "repo_slug": "whdrnr2583-cmd/token-meter", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_whdrnr2583_cmd_token_meter_aa7824dc/readme" }