ClaudeGlass

Are you using Claude Code well, or just burning tokens?

ClaudeGlass reads the transcripts Claude Code already keeps on your machine and shows where your tokens went: which sessions, subagents, cache rebuilds, CLAUDE.md files and habits cost the most, and the one change that would save the most next. Every suggestion comes with the evidence from your own sessions, what it trades away, and how to undo it.

It runs entirely on your computer: no telemetry, no API key, no account, and no runtime dependencies.

_{The Overview page. Synthetic data, 30-day window, subscription billing.}

Try it in a minute. check reads your history and prints what to change. It sets nothing up and changes nothing:

python -m pip install claudeglass
python -m claudeglass check --all-projects

With uv, uvx claudeglass check --all-projects does the same without installing anything.

What it finds · Quick start · What each page answers · Privacy · Documentation

What it finds

The questions people ask after a month of heavy Claude Code use, answered from your own sessions:

• "Which sessions were expensive, and why?" Every session and subagent run is priced, and the expensive ones say what drove the cost: a long context, a cache rebuild, a large tool output, or thinking.
• "Am I on the right model?" It finds agents on Opus or Sonnet doing work a cheaper model finishes just as well, and checks whether cheaper runs had to be redone by a larger model.
• "Why did my cache miss?" Each prompt-cache rebuild is dated and explained: a pause longer than the cache lifetime, a conversation summary, or a change early in the context.
• "What am I paying for on every reply?" CLAUDE.md files, skills and tool definitions go out with every request. It prices each one and says what to trim, move or hide.
• "Are my habits costing me?" Work habits turns each of your requests, and everything Claude did for it, into habits worth changing, with a rough saving for each.
• "Did my change work?" It records your settings as each session starts, and compares the sessions before a change with those after it.

Amounts follow how you pay: a share of your usage limits on a Pro or Max plan, dollars on pay-per-token billing.

Nothing changes by itself. Every recommendation is a prompt you give Claude or a command you run, and every command has a --dry-run.

Who it's for

• Developers who use Claude Code all day and keep reaching their Pro or Max usage limits.
• Engineers on API billing who want a smaller bill without worse work.
• Team leads who want to see how a team uses Claude Code without collecting anyone's sessions: see For team leads.

Quick start

About five minutes. You need Claude Code, already used for a while so there are sessions to look at, and Python 3.11 or newer. The commands below are for Windows PowerShell. On macOS or Linux, type them in Terminal with python3 in place of python.

Install it anywhere: it doesn't go into a repository. Claude Code keeps a transcript of every session, for every repository, in one folder (%USERPROFILE%\.claude\projects on Windows, ~/.claude/projects elsewhere), and ClaudeGlass reads that folder, so the dashboard shows all your repositories at once. Also run Claude Code inside WSL? Install it on Windows; see Using Claude Code in WSL too.

1. Check Python

python --version

It should print Python 3.11 or higher. If python isn't recognized, or the version is older, install Python from python.org. Tick Add python.exe to PATH in the installer, then open a new PowerShell window.

2. Install

python -m pip install claudeglass
python -m claudeglass --version

The second line should print claudeglass 0.9.0 or later. Prefer an isolated install? pipx install claudeglass or uv tool install claudeglass work too.

3. Set up

python -m claudeglass init

It asks up to four questions:

1. How you pay for Claude Code. 1 for a Pro, Max, Team or Enterprise plan, 2 for an API key. Amounts then show as a share of your usage limits, or in dollars.
2. Connect to Claude Code. It adds a small hook to your Claude Code settings.json that records which settings each session ran with. The dashboard uses it to show what changed and what that did. It adds no tokens.
3. Start the dashboard when you log on. Say yes. It starts straight away, and again every time you log on.
4. Sharper tips, optional. Claude ends each reply with a short tag, such as [tl: task=bugfix brief=clear], so the tips fit how you work. It costs a few hundred tokens a session and switches itself off after 14 days.

Then it lists every change and asks once: Go ahead? [Y/n/d]. Type d to see the exact settings.json change first, or n to change nothing. It backs settings.json up before changing it, and ends with a checklist of what's set up; python -m claudeglass status shows it again any time. init --advanced also asks about projects to leave out, the time zone, and the full metrics capture choices.

4. Open the dashboard

Go to http://127.0.0.1:8765 in your browser. On the first start, a banner shows its progress while it reads your history. That takes seconds to a few minutes, and figures fill in as it goes.

Start with Next best actions on the Overview page. Then open Actions › Checks, which answers one question per way of saving, such as "Is each agent on the cheapest model that does the job?". The dashboard only runs on your machine; nobody else can open it.

Other ways to install

Coming from claude-token-lens

ClaudeGlass was called claude-token-lens up to version 0.8.0. 0.9.0 is a fresh install, not an upgrade: remove the old tool first, then follow the quick start above.

python -m claude_token_lens uninstall --dry-run
python -m claude_token_lens uninstall
python -m pip uninstall claude-token-lens

The first command shows what the second removes: its hooks and status line in settings.json (backed up first), its skills and its logon task. Setting changes you made through it stay as they are. To keep your history, move %USERPROFILE%\.claude\token-lens to %USERPROFILE%\.claude\claudeglass before you run init.

What each page answers

The sidebar lists seven pages, with Data quality and the Glossary at its foot. A page with more than one part shows its segments beside its title.

The window picker at the top right sets the time every page covers. Pick the last hour, today or the last 24 hours to see the effect of a change straight away. Pick 7 to 90 days or all time for the long view, or since my last change. The project picker beside it narrows every page to one project. The theme button switches between your system's theme, light and dark. Setup › Capture and Glossary › Terms don't depend on the window, and say so.

Every view has its own address, such as #/spend/usage?w=30, so Back, Forward, bookmarks and shared links work, with the window and project kept. Search (Ctrl+K) finds pages, tables, recommendations, checks, glossary terms, recent sessions and projects. It also runs commands, such as setting the window or copying a prompt. Press ? for the keyboard shortcuts.

Every figure a recommendation rests on links to the table row it came from. A table that feeds a recommendation says so ("Feeds 2 actions"). Show as table on any chart gives the same figures as a grid.

Amounts follow your billing mode. On a Pro or Max plan, amounts are a share of your usage limits once the status line has logged enough usage-limit readings. Until then they're list-price equivalents: what the tokens would cost at Anthropic's published prices. On pay-per-token billing, amounts are what you pay.

Acting on a recommendation

_{A recommendation on the Actions page. Synthetic data.}

Each recommendation card explains the change before offering it. It says what the setting controls, its value now and after, which file it's written to and who that affects. Then it gives the expected effect, the trade-off, and how to undo it. There are two ways to make the change:

• Ask Claude to do it. Copy the prompt into Claude Code. It names the file, the setting and the value, and says why. It asks Claude to restate the change and show you the diff before saving. Claude Code asks your permission before editing files under .claude; that's expected.

• Or run the command. For a plain setting, the card shows a command such as:

  python -m claudeglass apply --set effortLevel=medium --scope user --dry-run
  

  --dry-run explains the change and prints the diff without writing anything. Run it again without --dry-run to make the change. The file is backed up first, and the output ends with the apply --revert <TS> command that undoes it. A revert won't run if the file was edited after the change, so it can't throw away your later edits. Add --ignore-changes to revert anyway.

The dashboard never changes a setting itself; there's no Apply button. Its commands use the form that runs on your machine.

Then restart Claude Code. It reads some settings, such as the model and effort level, only when a session starts, so a restart is the way to be sure. claude --continue picks your last conversation back up. Every card, apply and apply --revert remind you, and each prompt asks Claude to remind you once it has saved.

Profiles on Setup › Profiles work the same way for several settings at once. Each gives you a prompt, an apply <profile> --dry-run command, or a one-session trial (apply <profile> --launch) that leaves your settings files alone. See docs/profiles.md.

Updating

python -m claudeglass update

That one command:

• installs the newest version for this Python;
• restarts the dashboard on it, and checks that the dashboard answering on port 8765 is the new one. On Windows, if an older copy started by hand still holds the port, it names it and offers to stop it;
• brings the hook and status line entries this tool added to Claude Code's settings.json up to date. It shows each change and asks first, and backs up settings.json before any change;
• finds copies installed for other Pythons, and offers to remove the ones nothing uses any more.

Add --dry-run to see what it would do, or --yes to answer yes to every question. On macOS, restart the dashboard afterwards with launchctl kickstart -k gui/$(id -u)/com.claudeglass.

update is the one command that goes online: pip downloads the new version from GitHub. The foot of the dashboard's sidebar shows the version that is running. After an update the dashboard may read your history again once, so the first page load can be slow. CHANGELOG.md lists what changed.

Uninstalling

Look at what would be removed first:

python -m claudeglass uninstall --revert-changes --delete-data --dry-run

Then run the same command without --dry-run. It stops the dashboard, removes its logon task, the hooks and the status line, undoes any setting changes you made through this tool, and deletes its data, asking before each step. Leave out --revert-changes to keep your setting changes, or --delete-data to keep your history. Finally:

python -m pip uninstall claudeglass

If something goes wrong

Run python -m claudeglass status first: it says what's done, what's off and what needs attention, with the command that fixes each. Troubleshooting covers the rest, including an old dashboard that won't go away, an update that doesn't take and missing WSL sessions.

What it does to Claude Code, and how to undo it

• It uses no Claude tokens unless metrics capture is on. It reads files Claude Code has already written, and never calls Claude itself. Metrics capture is the one opt-in exception, and it's off by default. While it's on, Claude spends a few tokens in your own sessions, reading a short note and writing a tag. See docs/capture.md.
• It changes nothing on its own. init offers two optional additions, and shows each one and asks first:
  • a SessionStart hook that copies your settings into a local snapshot. It runs in the background, takes well under a second per session, and adds no tokens to the conversation;
  • a status line command that logs usage-limit readings. It adds no tokens, and Claude Code runs it only in a terminal session, not in the desktop app.
• Settings change only when you say so, through a prompt you give Claude or python -m claudeglass apply. apply backs the file up first and prints the command that undoes it. Flags such as --yes and --connect say yes for you, so leave them off to be asked.
• Cheaper isn't free. A cheaper model, lower effort or an earlier summary can make Claude less thorough. Each change says what it trades away. Try one change at a time. After a few sessions, check Your changes and what they did on Setup › Settings.

To see everything it installed, run python -m claudeglass changes or open the Data quality page; both say how to undo each item. To remove it completely, see Uninstalling.

Privacy

• What it reads. The transcripts in ~/.claude/projects. Through the SessionStart hook, it also reads your Claude Code settings, and the names and sizes of your CLAUDE.md files, skills and plugins. It keeps environment variable names, never their values, apart from a few numeric limits.
• What it keeps. Counts, token totals, costs and short labels such as tool and model names, in ~/.claude/claudeglass. Never message text, tool output, file contents, full paths or full commands. A test checks every field it reads from a transcript.
• What goes online. Only update, which runs pip to download the new version from GitHub. There's no telemetry and no update check. The dashboard listens only on 127.0.0.1, so other machines can't open it unless you pass --allow-remote. It loads nothing from the internet, and a test fails if its server opens an outbound connection.
• What metrics capture adds. It's off by default. When it's on, it adds a short note to your Claude Code sessions, and that note goes to Anthropic with the rest of the session. Claude's tags come back in its replies, and this tool reads them from your transcripts.

SECURITY.md is the full checklist for a security review, with the tests that back each point.

What it can't measure

• Your bill. There's no API to read back what a Claude Code session cost. Amounts come from the prices in pricing.toml, which you can edit. The tool never fetches prices.
• Dollars on a plan. On Pro or Max you don't pay per token, so amounts are a share of your usage limits. Until the status line has logged enough readings, they're list-price equivalents. Those are good for comparing setups, but they aren't an invoice.
• Usage limits outside a terminal. Usage-limit readings come from the status line, and Claude Code runs it only in a terminal session.
• Anything in an undocumented format, for certain. Claude Code's docs call the transcript format internal, and it changes between versions. The parser skips what it doesn't know rather than failing. It is tested against transcripts from Claude Code 2.1 (2.1.242 to 2.1.280), on Windows and Linux with Python 3.11 and 3.12.
• Quality, fully. A what-if estimate can't see whether a cheaper setting makes Claude less thorough. The quality signals on Agents & context › Quality help you check after a change.

docs/reference.md has the detail.

For team leads

• Exports. export writes CSV or JSON for a BI tool or an OpenTelemetry collector. By default it's aggregate-only, with project names hashed. See docs/exports.md.
• Team comparison. export --aggregate, import and team-report compare several people's machines without collecting anyone's sessions. Nobody is included unless they export and hand over the file. See docs/team.md.
• Monthly reports. monthly-report, or serve --monthly-report DIR while the dashboard runs, writes a one-month finance summary as Markdown and HTML.
• Confidential projects. exclude_projects in config.toml keeps a project out of everything; its transcripts are never read. See Settings for teams and enterprise.

Documentation

Glossary

The dashboard's Glossary page uses the same words, term for term.

Related tools

• ccusage: daily and monthly cost tables across several coding tools. ClaudeGlass covers only Claude Code, and goes deeper there. It splits the 5-minute and 1-hour cache, explains cache rebuilds, prices each subagent type and makes recommendations that know your settings.
• token-dashboard: the closest relative, with stdlib Python, SQLite and a web page. It removes duplicate replies by message id, prices each prompt and gives tips. ClaudeGlass adds a cache lifetime (TTL) simulation, the cause of each cache rebuild, costs per subagent type and before-and-after comparisons of your settings.
• cache-ttl-analyzer: replays the main conversation under a 5-minute and a 1-hour cache lifetime. ClaudeGlass does the same for each subagent type, and adds the wasted-write and near-miss measures.
• Claude-Code-Usage-Monitor: watches your live usage against the five-hour window. ClaudeGlass works alongside it: it explains why a session cost what it did, rather than watching the live burn rate.

Contributing

python -m pip install -e .[test]
python -m pytest -q

Use conventional commits (feat(parse): ..., docs(readme): ...), one focused change per commit. tests/helpers.py has the fixture builders the tests use, such as turn_line and write_jsonl; start there before writing a fixture by hand. Dashboard copy follows docs/writing-help.md. Report a security issue as SECURITY.md describes.

Licence

MIT. See LICENSE.