See where your Claude Code tokens go. Accurate counts, optimization tips, zero setup.
npx claude-code-pulseThat's it. A dashboard opens in your browser.
No install needed — just use npx:
npx claude-code-pulseOr install globally if you run it often:
npm install -g claude-code-pulse
claude-code-pulse- Total tokens — input, cached, and output broken out, with a week-over-week ↑/↓ trend
- Sessions — total session count and turns, with week-over-week delta
- Cache hit rate — percentage of tokens served from cache
- Avg tokens / session — average tokens per session and per turn
Toggle between 7D / 30D / 90D / All in the header, or click Custom to pick a specific start and end date. The filter applies globally — all tabs (Overview, Projects, Sessions, Tools, Prompts) update to reflect the selected time window.
- Usage heatmap — Monday-first GitHub-style calendar for the past 12 weeks, with month labels and hover tooltips showing date (dd-mm-yyyy) and token count
- Usage by hour of day — bar chart showing which hours you use Claude most (local time)
- Daily token usage — stacked bar chart of daily input, cache, and output tokens
- Model breakdown — donut chart of which Claude models you use most
Table of all projects ranked by token usage, with session count, turns, and API-equivalent cost.
- Best & Worst sessions — top 3 most efficient and 3 least efficient sessions scored by output ratio, cache reuse, and tool density
- All sessions table — full sortable list (Date, Tokens, Turns, Efficiency) with a color-coded efficiency score per session; click any row to open a session detail modal
Bar chart of your top 20 most-used Claude tools (Read, Edit, Bash, Grep, etc.) by call count.
Your 50 most token-heavy individual prompts, sortable by Date, Tokens, or Cost. Click any row to open the parent session detail.
Personalized tips based on your actual usage patterns — low cache hit rate, many short sessions, heavy Opus usage, high tool density, and more.
- Reads your local Claude Code session files from
~/.claude/projects/ - Parses and deduplicates the data (fixes counting bugs found in similar tools)
- Serves an interactive dashboard on
localhost:3456
Nothing leaves your machine. No network calls, no telemetry, no data collection.
These tips are also shown dynamically in the dashboard based on your actual usage:
Each new Claude Code session re-reads your project context. Staying in one session for related tasks reuses cached context, saving tokens.
Instead of "fix the bug", try "fix the null check in src/parser.js line 42". Specific prompts help Claude find what it needs with fewer tool calls.
If your session has grown very long, /compact summarizes the conversation to reduce context size for subsequent turns.
Opus is powerful but uses more tokens per turn. Sonnet handles most coding tasks well. Use /model to switch when appropriate.
Pasting relevant code snippets or file paths in your prompt reduces the number of Read/Grep tool calls Claude needs to make.
Extended thinking is great for complex problems but unnecessary for simple edits. /fast skips it for quicker, leaner responses.
| Flag | Description | Default |
|---|---|---|
--port <number> |
Port for the dashboard server | 3456 |
--no-open |
Don't auto-open the browser | opens automatically |
--help, -h |
Show help message | — |
Is this safe?
Yes. claude-code-pulse only reads files from ~/.claude/ on your machine and serves a dashboard on localhost. No data is sent anywhere.
Will it work on Windows?
Yes. File paths are resolved using Node.js os.homedir() and path.join, which work across platforms.
Why are the numbers different from claude-spend? claude-spend has a bug where streaming entries cause each assistant message to be counted 2-3 times, inflating all token numbers by ~3x. claude-code-pulse deduplicates by message ID, keeping only the final count per response.
What about the cost numbers? Cost is shown as "API-equivalent" for reference only. If you're on a Claude Pro ($20/mo) or Max ($100-200/mo) subscription, your actual cost is your subscription fee, not the API-equivalent amount.
Where is my data stored?
Claude Code stores session data in ~/.claude/projects/. claude-code-pulse reads these files and optionally caches parsed results in ~/.claude/pulse-cache.json for faster subsequent runs.
- All data stays on your machine
- Zero network requests — Chart.js is bundled locally, no CDN calls
- No telemetry or analytics
- No data is written except an optional local cache file
- Dashboard binds to localhost only — not accessible from other machines on your network
MIT