Overview
ClaudeSavvy is a free, open-source local web dashboard for tracking Claude Code usage. It reads Claude Code's session files from your machine and serves a full analytics dashboard at http://localhost:5000 — no cloud, no account, no data leaving your machine.
It covers every angle of your Claude Code activity: token costs by project and conversation, MCP server call volumes, tool usage patterns, sub-agent token exchanges, file edits, context growth, cache hit rates, and your full Claude Code configuration. All filterable by time period and model.
~/.claude/ on your machine. No accounts, no telemetry, no data sent anywhere. MIT licensed and open source.
Installation
Install from PyPI:
pip install claudesavvyRequires Python 3.9 or later. Or install from source:
git clone https://github.com/allannapier/claudesavvy.git
cd claudesavvy
pip install -e .Verify the install:
claudesavvy --versionQuick Start
Launch the dashboard by running claudesavvy in your terminal. It starts a local web server and opens http://localhost:5000 in your browser automatically.
claudesavvyThe dashboard reads all Claude Code session data from ~/.claude/projects/ immediately. No configuration needed — if you've run Claude Code before, your data is already there.
Dashboard — Overview Metrics
The Dashboard is your home screen. It shows four headline metrics at the top:
Cache Hit Rate — the percentage of input tokens served from the prompt cache. A high rate means you're saving money on repeated context. Cache Savings is the estimated dollar amount saved by cache reads vs paying full input token price.
Below the headline metrics, the Dashboard shows an Explore Your Usage section with quick-link cards to every other page — showing a live summary (e.g. "7 MCP servers, 803 total calls") so you can see what's interesting at a glance.
The bottom of the Dashboard shows a Model Usage breakdown — which models you've used, their share of total tokens, and their cost contribution.
Charts & Heatmap
The Dashboard includes four charts:
Token Usage Heatmap
A GitHub-style contribution heatmap showing daily token volume over the past 12 months. Each cell represents one day; darker = more tokens. Hover to see the exact count. Great for spotting usage spikes and patterns over time.
Cost Over Time
A line chart of your daily spend within the selected time period. Click View breakdown to see cost split by model or project.
Cost Breakdown
A donut/pie chart showing cost distribution across projects or models. Click View breakdown to switch dimensions.
Project Costs Over Time
A stacked area chart showing how each project's cost contributes to total spend over the selected period. Click View all projects to go to the Projects page.
Export
The Dashboard has an Export button in the top-right that lets you download your usage data. Use this to back up your analytics, import into a spreadsheet, or share with your team.
Token Usage
The Tokens page gives a detailed breakdown of every token type consumed. Filter by Model and Time Period independently — useful for comparing token patterns across claude-opus vs claude-sonnet, for example.
Metrics shown
- Input Tokens — new (non-cached) input tokens sent to the model
- Output Tokens — tokens generated by the model in responses
- Total Input* — combined input including cache reads (marked with asterisk)
- Cache Reads — tokens served from the prompt cache (at reduced cost)
Understanding the split between fresh input and cache reads helps you evaluate how well your prompts are taking advantage of Claude's prompt caching. A high cache read share means lower costs per turn.
Projects
The Projects page shows per-project usage analytics. Each project corresponds to a working directory where you've run Claude Code. Filter by Model and Time Period.
Metrics shown
- Total Projects — number of distinct projects in the selected period
- Avg Commands/Project — average number of Claude Code commands per project
- Most Active Project — the project with the most activity
All Projects table
The table lists every project with its total cost, session count, and other stats. Click any project to drill into its conversations. Costs are calculated using Anthropic's official per-token pricing for each model — unrecognised model IDs fall back to Claude Sonnet 4.5 rates.
Conversations
The Conversations page is one of ClaudeSavvy's most powerful views. It shows every Claude Code conversation with rich analytics — sorted by cost by default.
Summary metrics
Conversations table columns
| Column | Description |
|---|---|
| Project | Project name and model used for this conversation |
| Started | Date and time the conversation began |
| Duration | Total elapsed time from first to last turn |
| Turns | Number of message exchanges in the conversation |
| Total Tokens | Combined token count across all turns |
| Peak Context | Largest context window used, with a visual fill bar showing proportion of max context |
| Cache % | Percentage of input tokens served from cache for this conversation |
| Cost | Total cost for the conversation |
Context growth chart
Click any row in the conversation table to open a context growth chart for that conversation — a line chart showing how the context window grew turn by turn. This is invaluable for understanding which conversations ballooned in context (and cost) and why.
Files
The Files page shows file-level activity statistics — which files Claude Code has read, written, or modified, and how many times.
Summary metrics
- Total Files — number of unique files touched in the period
- Most Edited File — the file with the most operations
- Total Operations — sum of all file reads, writes, and edits
- Projects with Files — how many projects have file activity data
The Recent File Operations table lists each file with its project, operation count, and total activity. Useful for auditing which files Claude Code has touched most during a session or period.
Integrations — MCP Servers
The Integrations page tracks your MCP (Model Context Protocol) server usage — showing which external tools and servers Claude Code called, how many times, and at what token/cost cost.
Summary metrics
- MCP Servers — number of distinct MCP servers called in the period
- Total Calls — sum of all MCP tool invocations
- Total Tokens — tokens attributed to MCP tool calls
- Total Cost — estimated cost of MCP-related token usage
The detail table breaks these down per server — for example, showing that chrome-devtools was called 803 times in a period. This helps identify which integrations are consuming the most context.
Features & Tools
The Features page tracks which Claude Code tools (Bash, Read, Write, Glob, Agent, Skill, etc.) were called, how many times, and what they cost. Two views are available via tabs.
Tools Overview tab
Summary metrics: Total Tools Used, Total Calls, Total Tokens, Total Cost, Sub-Agents Used.
The Tool Usage table lists every tool with: call count, tokens consumed, estimated cost per call, and total estimated cost. Click any row to see a detailed token breakdown by conversation for that tool.
| Column | Description |
|---|---|
| Tool Name | The Claude Code tool (Bash, Read, Write, Glob, Edit, Agent, Skill, etc.) |
| Category | Tool type (always "tool" in current version) |
| Calls | Number of times this tool was invoked |
| Tokens | Total tokens attributed to calls of this tool |
| Cost/Call | Estimated average token cost per invocation |
| Est. Cost | Total estimated cost across all calls of this tool |
Unified Timeline tab
Switches to a chronological view of all tool calls across all sessions — showing exactly when each tool was called and in which conversation. Useful for reconstructing what happened in a session or identifying patterns in tool usage over time.
Sub-Agents
The Sub-Agents page tracks token exchanges from Task tool sub-agent invocations — when Claude Code launches a sub-agent (another Claude instance) to handle a delegated task.
Metrics shown
- Total Exchanges — number of sub-agent invocations recorded
- Total Tokens — tokens consumed across all sub-agent exchanges
- Total Cost — cost attributed to sub-agent usage
- Avg Tokens/Exchange — average token load per sub-agent invocation
Sub-agent token tracking helps you understand the overhead of agentic workflows — particularly useful if you're building pipelines where Claude Code delegates to specialised sub-agents.
Teams
The Teams page tracks token usage for the Claude Code Teams feature — when Claude Code runs as a shared tool across a team, with usage aggregated per member.
Metrics shown
- Total Team Runs — number of team-mode sessions recorded
- Total Tokens — combined token usage across all team runs
- Total Cost — total cost attributed to team usage
Configuration Viewer
The Configuration page is a read-only browser for your Claude Code configuration — showing every skill, MCP server, slash command, plugin, hook, and agent defined across your user config and all your projects.
Repository selector
Use the Repository dropdown to switch between your user-level configuration (User Configuration) and any of your project directories. Each project's CLAUDE.md and settings files are parsed and displayed.
What's shown
- Skills — custom skills defined in your Claude Code config
- MCPs — MCP servers configured for this context
- Commands — slash commands defined (e.g.
/commit,/review-pr) - Plugins — Claude Code plugins installed
- Hooks — event hooks configured (pre/post tool use, session start, etc.)
- Agents — custom agent definitions
Click any category tab (Skills, MCPs, Commands, Plugins, Hooks, Agents) to see the full list with descriptions. Use the Export button to download the configuration as JSON. The Refresh button re-reads config files from disk.
Status Line
ClaudeSavvy can install a live status line directly into Claude Code's terminal interface — showing your today's cost, token count, cache hit rate, session count, and monthly spend, updated in real-time as you work.
One-click install
Go to Settings in ClaudeSavvy and click One-click install. ClaudeSavvy will:
- Install the status line script into your Claude Code setup
- Configure
settings.jsonto run the script automatically - Show a live preview of what the status line will look like
Once installed, the status line appears at the bottom of every Claude Code session. You'll see a confirmation that Script installed and settings.json configured.
To remove the status line, go to Settings and uninstall — ClaudeSavvy will clean up the script and revert settings.json.
Model Pricing Configuration
ClaudeSavvy calculates costs using bundled pricing tables for each model. If you need to override pricing (e.g. for a private model deployment or to keep up with a price change), you can set custom rates in Settings → Model Pricing Configuration.
For each model you can set:
- Input (per million tokens) — cost per 1M input tokens
- Output (per million tokens) — cost per 1M output tokens
- Cache Write (per million tokens) — cost per 1M cache write tokens
Changes are applied immediately to all cost calculations across every page. This is particularly useful for tracking costs on private or enterprise Claude deployments with negotiated pricing.
Time Filters
Every page in ClaudeSavvy has a time period selector. Available options:
| Option | What it shows |
|---|---|
| Last 15 min | The past 15 minutes only — great for checking the cost of your last command |
| Today | From midnight to now (default on most pages) |
| This week | From the start of the current week (Monday) |
| Last 7 days | Rolling 7-day window ending now |
| This month | From the 1st of the current month |
| Last 3 months | Rolling 90-day window |
| All time | All session data ClaudeSavvy has read (default on Teams page) |
| Custom range… | Pick a specific start and end date |
The Tokens page also has an independent Model filter, letting you isolate usage for a specific model (e.g. claude-opus-4-6 only) within any time period.
FAQ
Does it send my data anywhere?
No. ClaudeSavvy is a local web server — it reads from ~/.claude/ and serves the dashboard at localhost:5000. No analytics, no telemetry, no external requests. MIT licensed.
Why don't I see any data?
You need at least one completed Claude Code session. Run a Claude Code session first, then launch ClaudeSavvy. If sessions exist but data doesn't appear, check that ~/.claude/projects/ contains .jsonl session files.
What Claude Code versions are supported?
ClaudeSavvy works with Claude Code CLI 1.x and later. If you're on an older version, upgrade with npm update -g @anthropic-ai/claude-code.
Can I filter by project across all pages?
Some pages filter automatically when you navigate from the Dashboard or Projects view. Global project filtering across all pages is on the roadmap.
Does it work with Claude Code Teams?
Yes — the Teams page aggregates team-mode session data. Individual usage always shows in the standard analytics pages regardless of account type.
Can I export my data?
Yes — use the Export button on the Dashboard. The Configuration page also has an Export option for your Claude Code config. More export formats are planned.
How do I update ClaudeSavvy?
pip install --upgrade claudesavvyCheck the GitHub releases page for changelog details. After updating, restart the server for new features and pricing updates to take effect.