tokenmeter-dashboard 0.2.0__tar.gz

tokenmeter_dashboard-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serkan Korkut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenmeter_dashboard-0.2.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: tokenmeter-dashboard
+Version: 0.2.0
+Summary: Local token usage, cost and limits dashboard for Claude Code, Codex and GitHub Copilot CLI
+Author: Serkan Korkut
+License: MIT
+Project-URL: Homepage, https://github.com/serkankorkut/tokenmeter
+Project-URL: Source, https://github.com/serkankorkut/tokenmeter
+Keywords: claude-code,codex,copilot,tokens,cost,dashboard,llm
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Tokenmeter
+
+![Tokenmeter demo](https://raw.githubusercontent.com/serkankorkut/tokenmeter/main/docs/demo.gif)
+
+A local dashboard that shows token usage and estimated cost for every prompt you send in **Claude Code** and **Codex**. Zero dependencies: one Python file, one HTML file, nothing leaves your machine.
+
+## 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 or Codex. Both tools 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:
+
+```bash
+brew install serkankorkut/tap/tokenmeter
+```
+
+```bash
+pipx install tokenmeter-dashboard
+```
+
+```bash
+uvx tokenmeter-dashboard
+```
+
+Or, as a Claude Code plugin straight from GitHub:
+
+```bash
+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:
+
+```bash
+git clone https://github.com/serkankorkut/tokenmeter ~/repo/tokenmeter
+~/repo/tokenmeter/install.sh
+```
+
+With Homebrew you can keep it running in the background: `brew services start tokenmeter`.
+
+Then in either tool:
+
+```
+/tokenmeter
+```
+
+or from a shell:
+
+```bash
+tokenmeter --open
+```
+
+## Configuration
+
+Everything lives in `pricing.json` next to `server.py`:
+
+| 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 |
+| `_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 |
+
+Environment and flags:
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `TOKENMETER_PORT` / `--port` | `7788` | Listen port |
+| `--host` | `127.0.0.1` | Bind address. Use `0.0.0.0` only for a team server |
+| `--open` | | Open the browser after starting |
+| `--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 team data is stored |
+
+### 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
+
+```bash
+python3 test_server.py
+python3 -m tokenmeter --open
+```
+
+Release: bump the version in `pyproject.toml` and `tokenmeter/__init__.py`, tag `vX.Y.Z` and push. The GitHub Action publishes to PyPI via trusted publishing. Then regenerate the Homebrew formula with `release/brew-formula.sh > ../homebrew-tap/Formula/tokenmeter.rb`.
+
+## 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

tokenmeter_dashboard-0.2.0/README.md

@@ -0,0 +1,147 @@
+# Tokenmeter
+
+![Tokenmeter demo](https://raw.githubusercontent.com/serkankorkut/tokenmeter/main/docs/demo.gif)
+
+A local dashboard that shows token usage and estimated cost for every prompt you send in **Claude Code** and **Codex**. Zero dependencies: one Python file, one HTML file, nothing leaves your machine.
+
+## 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 or Codex. Both tools 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:
+
+```bash
+brew install serkankorkut/tap/tokenmeter
+```
+
+```bash
+pipx install tokenmeter-dashboard
+```
+
+```bash
+uvx tokenmeter-dashboard
+```
+
+Or, as a Claude Code plugin straight from GitHub:
+
+```bash
+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:
+
+```bash
+git clone https://github.com/serkankorkut/tokenmeter ~/repo/tokenmeter
+~/repo/tokenmeter/install.sh
+```
+
+With Homebrew you can keep it running in the background: `brew services start tokenmeter`.
+
+Then in either tool:
+
+```
+/tokenmeter
+```
+
+or from a shell:
+
+```bash
+tokenmeter --open
+```
+
+## Configuration
+
+Everything lives in `pricing.json` next to `server.py`:
+
+| 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 |
+| `_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 |
+
+Environment and flags:
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `TOKENMETER_PORT` / `--port` | `7788` | Listen port |
+| `--host` | `127.0.0.1` | Bind address. Use `0.0.0.0` only for a team server |
+| `--open` | | Open the browser after starting |
+| `--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 team data is stored |
+
+### 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
+
+```bash
+python3 test_server.py
+python3 -m tokenmeter --open
+```
+
+Release: bump the version in `pyproject.toml` and `tokenmeter/__init__.py`, tag `vX.Y.Z` and push. The GitHub Action publishes to PyPI via trusted publishing. Then regenerate the Homebrew formula with `release/brew-formula.sh > ../homebrew-tap/Formula/tokenmeter.rb`.
+
+## 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

tokenmeter_dashboard-0.2.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokenmeter-dashboard"
+version = "0.2.0"
+description = "Local token usage, cost and limits dashboard for Claude Code, Codex and GitHub Copilot CLI"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{name = "Serkan Korkut"}]
+keywords = ["claude-code", "codex", "copilot", "tokens", "cost", "dashboard", "llm"]
+classifiers = [
+  "Environment :: Web Environment",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development",
+  "Topic :: System :: Monitoring"
+]
+
+[project.urls]
+Homepage = "https://github.com/serkankorkut/tokenmeter"
+Source = "https://github.com/serkankorkut/tokenmeter"
+
+[project.scripts]
+tokenmeter = "tokenmeter.server:main"
+
+[tool.setuptools]
+packages = ["tokenmeter"]
+
+[tool.setuptools.package-data]
+tokenmeter = ["index.html", "pricing.json"]

tokenmeter_dashboard-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokenmeter_dashboard-0.2.0/tokenmeter/__init__.py

@@ -0,0 +1 @@
+from tokenmeter.server import __version__

tokenmeter_dashboard-0.2.0/tokenmeter/__main__.py

@@ -0,0 +1,3 @@
+from tokenmeter.server import main
+
+main()