{"id":49720088,"url":"https://github.com/phuryn/claude-usage","last_synced_at":"2026-06-09T01:09:09.285Z","repository":{"id":349846288,"uuid":"1204165003","full_name":"phuryn/claude-usage","owner":"phuryn","description":"A local dashboard for tracking your Claude Code token usage, costs, and session history. Pro and Max subscribers get a progress bar. This gives you the full picture.","archived":false,"fork":false,"pushed_at":"2026-04-24T03:19:05.000Z","size":1538,"stargazers_count":1238,"open_issues_count":22,"forks_count":198,"subscribers_count":13,"default_branch":"main","last_synced_at":"2026-04-24T04:27:51.951Z","etag":null,"topics":["claude-code"],"latest_commit_sha":null,"homepage":"https://www.productcompass.pm/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phuryn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-07T18:49:32.000Z","updated_at":"2026-04-24T03:19:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phuryn/claude-usage","commit_stats":null,"previous_names":["phuryn/claude-usage"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/phuryn/claude-usage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fclaude-usage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fclaude-usage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fclaude-usage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fclaude-usage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phuryn","download_url":"https://codeload.github.com/phuryn/claude-usage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fclaude-usage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33475746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code"],"created_at":"2026-05-09T00:00:28.508Z","updated_at":"2026-06-09T01:09:09.276Z","avatar_url":"https://github.com/phuryn.png","language":"Python","funding_links":[],"categories":["📊 Usage \u0026 Observability"],"sub_categories":[],"readme":"# Claude Code Usage Dashboard\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)\n[![claude-code](https://img.shields.io/badge/claude--code-black?style=flat-square)](https://claude.ai/code)\n\n**Pro and Max subscribers get a progress bar. This gives you the full picture.**\n\nClaude Code writes detailed usage logs locally — token counts, models, sessions, projects — regardless of your plan. This dashboard reads those logs and turns them into charts and cost estimates. Works on API, Pro, and Max plans.\n\n![Claude Usage Dashboard](docs/screenshot.png)\n\n**Created by:** [The Product Compass Newsletter](https://www.productcompass.pm)\n\n---\n\n## What this tracks\n\nWorks on **API, Pro, and Max plans** — Claude Code writes local usage logs regardless of subscription type. This tool reads those logs and gives you visibility that Anthropic's UI doesn't provide.\n\nCaptures usage from:\n- **Claude Code CLI** (`claude` command in terminal)\n- **VS Code extension** (Claude Code sidebar)\n- **Dispatched Code sessions** (sessions routed through Claude Code)\n\n**Not captured:**\n- **Cowork sessions** — these run server-side and do not write local JSONL transcripts\n\n---\n\n## Requirements\n\n- Python 3.8+\n- No third-party packages — uses only the standard library (`sqlite3`, `http.server`, `json`, `pathlib`)\n\n\u003e Anyone running Claude Code already has Python installed.\n\n## Quick Start\n\nNo `pip install`, no virtual environment, no build step.\n\n### macOS / Linux (Homebrew)\n```\nbrew install --formula https://raw.githubusercontent.com/phuryn/claude-usage/main/Formula/claude-usage.rb\nclaude-usage dashboard\n```\n\nAfter install, the `claude-usage` command is on your `PATH` and accepts the same subcommands as `python cli.py` (`scan`, `today`, `stats`, `dashboard`).\n\n### macOS / Linux (clone)\n```\ngit clone https://github.com/phuryn/claude-usage\ncd claude-usage\npython3 cli.py dashboard\n```\n\n### Windows\n```\ngit clone https://github.com/phuryn/claude-usage\ncd claude-usage\npython cli.py dashboard\n```\n\n\n---\n\n## Usage\n\n\u003e On macOS/Linux, use `python3` instead of `python` in all commands below. If you installed via Homebrew, replace `python cli.py` with `claude-usage`.\n\n```\n# Scan JSONL files and populate the database (~/.claude/usage.db)\npython cli.py scan\n\n# Show today's usage summary by model (in terminal)\npython cli.py today\n\n# Show the last 7 days (per-day breakdown + by-model totals)\npython cli.py week\n\n# Show all-time statistics (in terminal)\npython cli.py stats\n\n# Scan + open browser dashboard at http://localhost:8080\npython cli.py dashboard\n\n# Custom host and port via environment variables\nHOST=0.0.0.0 PORT=9000 python cli.py dashboard\n\n# Scan a custom projects directory\npython cli.py scan --projects-dir /path/to/transcripts\n```\n\nThe scanner is incremental — it tracks each file's path and modification time, so re-running `scan` is fast and only processes new or changed files.\n\nBy default, the scanner checks both `~/.claude/projects/` and the Xcode Claude integration directory (`~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/projects/`), skipping any that don't exist. Use `--projects-dir` to scan a custom location instead.\n\n---\n\n## How it works\n\nClaude Code writes one JSONL file per session to `~/.claude/projects/`. Each line is a JSON record; `assistant`-type records contain:\n- `message.usage.input_tokens` — raw prompt tokens\n- `message.usage.output_tokens` — generated tokens\n- `message.usage.cache_creation_input_tokens` — tokens written to prompt cache\n- `message.usage.cache_read_input_tokens` — tokens served from prompt cache\n- `message.model` — the model used (e.g. `claude-sonnet-4-6`)\n\n`scanner.py` parses those files and stores the data in a SQLite database at `~/.claude/usage.db`.\n\n`dashboard.py` serves a single-page dashboard on `localhost:8080` with Chart.js charts (loaded from CDN). It auto-refreshes every 30 seconds and supports model filtering with bookmarkable URLs. The bind address and port can be overridden with `HOST` and `PORT` environment variables (defaults: `localhost`, `8080`).\n\n---\n\n## Cost estimates\n\nCosts are calculated using **Anthropic API pricing as of April 2026** ([claude.com/pricing#api](https://claude.com/pricing#api)).\n\n**Only models whose name contains `opus`, `sonnet`, or `haiku` are included in cost calculations.** Local models, unknown models, and any other model names are excluded (shown as `n/a`).\n\n| Model | Input | Output | Cache Write | Cache Read |\n|-------|-------|--------|------------|-----------|\n| claude-opus-4-7 | $5.00/MTok | $25.00/MTok | $6.25/MTok | $0.50/MTok |\n| claude-opus-4-6 | $5.00/MTok | $25.00/MTok | $6.25/MTok | $0.50/MTok |\n| claude-sonnet-4-6 | $3.00/MTok | $15.00/MTok | $3.75/MTok | $0.30/MTok |\n| claude-haiku-4-5 | $1.00/MTok | $5.00/MTok | $1.25/MTok | $0.10/MTok |\n\n\u003e **Note:** These are API prices. If you use Claude Code via a Max or Pro subscription, your actual cost structure is different (subscription-based, not per-token).\n\n---\n\n## VS Code extension\n\nIf you'd rather see the dashboard inside your editor, the same UI is available as a VS Code extension. Same data, same charts, embedded as an activity-bar sidebar.\n\n[**Install from the VS Code Marketplace →**](https://marketplace.visualstudio.com/items?itemName=PawelHuryn.claude-usage-phuryn)\n\n![VS Code extension — daily usage](docs/usage1.png)\n![VS Code extension — hourly + projects](docs/usage2.png)\n\nThe Python sources are bundled inside the `.vsix`, so the only end-user requirement is **Python 3.8+ on your `PATH`**. After install, click the gauge icon in the activity bar — the server spawns automatically and the dashboard renders in the sidebar.\n\nSee [vscode-extension/README.md](vscode-extension/README.md) for settings, commands, discovery order, and local-install instructions.\n\n---\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `scanner.py` | Parses JSONL transcripts, writes to `~/.claude/usage.db` |\n| `dashboard.py` | HTTP server + single-page HTML/JS dashboard |\n| `cli.py` | `scan`, `today`, `stats`, `dashboard` commands |\n| `Formula/claude-usage.rb` | Homebrew formula — install with `brew install --formula \u003craw-url\u003e` |\n| `vscode-extension/` | VS Code extension — embeds the dashboard inside VS Code |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphuryn%2Fclaude-usage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphuryn%2Fclaude-usage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphuryn%2Fclaude-usage/lists"}