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 on your computer: no telemetry, no API key, no account, and no runtime dependencies. Only the optional metrics capture asks Claude anything, through your own Claude Code login.

_{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. It also names the agents that wrote code on Opus or Fable only because nothing set their 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, and what MCP tool search saves by keeping unused tool definitions out, server by server. An MCP server Claude never uses is named, with how to turn it off for its kind.
• "Do my hooks work?" Each hook you set up is checked against your sessions: how often it failed and when it last did, the calls it blocked, and what the context it adds costs. A hook that has stopped failing drops out of the fix.
• "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. How you prompt counts the prompting habits that cost extra replies, such as small requests sent one at a time or the same request sent again, and what each cost. Turn on coaching notes and you're told the moment you send one.
• "Did my change work?" It records your settings as each session starts, and compares the sessions before a change with those after it: Your changes shows each one's effect on the measures it should move, such as tokens per session for a model change, how sure it is, and what it saved so far.

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.11.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, and, unless you have one already, a status line that logs your usage-limit readings. The dashboard uses them to show what changed and what that did. Neither adds 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 and off unless you say yes. Claude ends each reply with a short tag, such as [cg: task=bugfix brief=clear], so the tips fit how you work. This turns on metrics capture at its Essentials level: about 186 tokens when a session starts and 14 per reply, plus a Claude Haiku call of about $0.002 after each subagent run. It switches itself off after 14 days. It also adds the /cg-feedback skill, for rating a piece of work when it's done.

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, WSL folders, where changes are written, 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 the Overview. It answers three questions: is anything wrong, did your changes work, and where do your tokens go. 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. It's made for a desktop browser window.

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 opens with the three pages that answer what people come with: the Overview, Your changes and Actions. Under Details are the pages with the evidence behind them, and Data quality and the Glossary sit 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: it shows the diff again and asks before it writes. 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 hooks and status line this tool added to Claude Code's settings.json up to date, metrics capture's included. It shows each change and asks first, and backs up settings.json before any change;
• brings the /cg-feedback and /cg-brief skills it added up to date, and renames them from their earlier names (/tl-feedback or /cl-feedback, /tl-brief or /cl-brief), asking first;
• finds copies installed for other Pythons, and offers to remove the ones nothing uses any more.

On Windows, if only an administrator can write to Python's Scripts folder, pip would fail part way through. update checks first, and asks you to run it again from a terminal opened as administrator.

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 only command that downloads anything: pip fetches 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, its hooks, status line and skills, 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 you turn on metrics capture or coaching notes. Otherwise it only reads files Claude Code has already written. Both are off by default, and both are described below.
• It changes nothing on its own. init, capture and update show each change to Claude Code's settings.json and ask first, and back the file up before changing it. The dashboard never changes it.
• 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 init --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 the Your changes page.

What it adds

To see everything it installed, run python -m claudeglass changes or open the Data quality page; both say how to undo each item. python -m claudeglass capture remove takes capture's and coaching's entries out of settings.json. To remove it completely, see Uninstalling.

Metrics capture

Metrics capture is opt-in, and off by default. Each level adds to the one before it:

The note is written to the prompt cache once, then read from it on each later reply. Capture switches itself off 14 days after you turn it on: --for sets another length, and --no-limit removes the limit. [capture] sample in config.toml runs it in only a share of sessions. Setup › Capture replays your last 14 days against each level before you pick one, and measures the real cost once it's on. Scripts that run claude -p or the Agent SDK get nothing added.

Who writes the tags. By default, Claude writes the tag at the end of its reply. python -m claudeglass capture tagger haiku has Claude Haiku write it after each turn instead, for about $0.002 a turn. Claude's replies then carry no tag, and at Essentials and Standard its session-start note goes too. Either way, Haiku judges each finished subagent run, and the subagent itself is asked for nothing.

docs/capture.md lists every metric, what it costs and what it feeds.

Live coaching

Live coaching has its own switches, on Setup › Capture or with capture enable and capture disable. All three are off by default, and they work at any capture level, Off included:

• Coaching notes (coaching_notes). When a hint applies, such as a large tool output, an expired cache or several small requests in a row, the hook adds a short note and Claude passes the tip on. For the six prompting habits, you also see a one-line notice the moment you send the message. They're made for the desktop app, where the status line doesn't show.
• Coaching line (coaching_line). The same kind of hint in the status line, in a terminal. It costs no tokens.
• Brief templates (capture brief on). Checklists per kind of task on Work habits, and the /cg-brief skill, which checks a request against its checklist and asks once for anything missing.

For example, python -m claudeglass capture enable coaching_notes turns on coaching notes. See docs/coaching.md.

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. With coaching notes on, the hook reads each message you send, and your recent ones, for their length, timing and shared words. Nothing about your words is kept.
• 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. ClaudeGlass itself sends nothing, except 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. Metrics capture is the exception: it asks Claude Haiku, as the next point says.
• What metrics capture and coaching notes send. Both are off by default.
  • Their notes go into your Claude Code sessions, so they reach Anthropic with the rest of the session. Claude's tags come back in its replies, and this tool reads them from your transcripts.
  • From Essentials up, the capture hook sends Claude Haiku a short excerpt of each finished subagent run, through your own Claude Code login. The excerpt holds the run's brief, the end of its report, the files it changed and the first line of its shell commands, each cut to a set length. Haiku judges every run this way, whoever writes the tags.
  • With tagger = "haiku", the hook also sends Haiku an excerpt of each turn, mainly your message and the end of Claude's reply, and Haiku writes the tag.
  • Only Haiku's answer is kept, in a local file: a few words from a fixed list, with its cost and token counts. The excerpt isn't kept.

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. Where Claude Code writes down its own cost figure for a session, Actions › Checks compares the two.
• 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.260 to 2.1.283), 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.