Setup Guide

Find the ghost tokens
burning your Claude Code

By Dan Donovan, @askdandonovan

A free, open-source tool that shows exactly where your Claude Code usage is going. One command finds the invisible overhead eating your limits on every single message.

3 Steps
~2 min Setup time
0 Usage cost
Free Forever

What is Token Optimizer?

It's a Python tool that scans your Claude Code setup and shows you exactly how many tokens each component costs (every skill, MCP server, config file, and system prompt) so you can cut the waste you didn't know was there.

What you'll have after this
Token breakdown
Exact token count for every skill, MCP server, and config file
Biggest offenders
Ranked list of what's burning the most usage
Fix recommendations
Specific suggestions with before/after diffs
Session quality score
How much your AI's accuracy has degraded this session

Why this matters

Ghost tokens don't load once. They get re-sent on every single message. Here's what that looks like for a typical power user:

Ghost tokens per message 50,000
Messages before hitting limit x 30
Tokens burned on nothing 1,500,000
That's why you hit your cap halfway through the day. Most power users find 50,000-70,000 tokens of pure waste from skills they installed and forgot, MCP servers they don't use, and bloated config files.
Before you start: You need two things:

1. Claude Code already installed (install guide).
2. Python 3.8 or higher. Open Terminal and type python3 --version to check. If you see an error or a version below 3.8, download Python from python.org.
1

Install Token Optimizer

Open your Terminal and paste this command. It clones the tool into your Claude Code directory and sets everything up automatically.

Terminal 
curl -fsSL https://raw.githubusercontent.com/alexgreensh/token-optimizer/main/install.sh | bash

You'll see it install in about 10 seconds. It creates a folder at ~/.claude/token-optimizer and links itself as a Claude Code skill.

2

Run your first scan

Open Claude Code and type this. It runs the quick scan, which takes about 10 seconds and immediately shows your biggest token offenders.

Claude Code 
/token-optimizer quick

You'll see a breakdown of every component and how many tokens it costs. The tool highlights anything above a threshold and flags unused components.

Zero usage cost. Token Optimizer runs as an external Python script, not inside your Claude Code context. It doesn't consume any of your plan usage to scan.
3

Read the results and fix

The scan shows you exactly what's costing tokens. Now you decide what to cut. Token Optimizer won't change anything without showing you a diff first.

Common things it finds:

  • Skills you installed and forgot: still loaded every message
  • MCP servers you don't use: each one adds thousands of tokens
  • Bloated CLAUDE.md files: instructions that could be half the length
  • Duplicate configs: same setting defined in multiple places

Want the full picture? Run the interactive audit with guided fixes:

Claude Code 
/token-optimizer

This runs 6 parallel analysis agents and walks you through each fix with before/after diffs. It backs up everything before changing anything.

?

What to try after setup

Once installed, you've got a full toolkit for understanding your Claude Code usage. Here are the most useful commands:

Session health check 
/token-optimizer quality

Shows a 7-signal quality score for your current session. Tells you how much your AI's accuracy has degraded and whether you should start a fresh session.

See where money goes 
/token-optimizer dashboard

Opens an interactive HTML dashboard with per-session costs, per-turn token breakdowns, trend charts, and spike detection.

Anti-pattern detection 
/token-optimizer coach

Detects 8 named anti-patterns (like "The Kitchen Sink": too many skills loaded) and gives you specific fixes for each one.

Track savings over time 
/token-optimizer savings

Shows cumulative dollar savings from optimisations you've made, with daily averages and monthly estimates.

The tool that pays for itself in the first scan. Power users regularly discover 50,000+ tokens of waste: skills they tried once three months ago, MCP servers from tutorials they followed, config files they copy-pasted from Reddit. All of it silently re-sent on every message, every session, every day. One scan, and it stops.