avivavi/tokenscope

TokenScope is a tool for people using Claude Code who want to understand where their token budget actually goes. Claude Code is an AI coding assistant, and every time you interact with it, the conversation consumes tokens, which cost money. Claude Code already saves records of these sessions to your disk as JSON files. TokenScope reads those files and gives you a clear picture of what happened, rather than trying to predict what a task might cost in advance. The tool runs locally on your machine with no dependencies, requiring only Node version 18 or higher. You can run it without installing anything by using the npx command. It gives you an overview of all your projects, flags the biggest sources of wasted tokens, and can break down individual sessions for a specific project. It also generates a file called CODEMAP.md, which is a lightweight map of your repository that an AI agent can read instead of opening entire files. A central feature is the Context Score, a zero to one hundred grade for each project based on five measured signals. These include cache efficiency, error rate, repeated file reads, and other forms of waste. Importantly, spending a lot of tokens does not guarantee a low score. The grade only drops for actual waste, not for spending that serves your work. Each component of the score also shows an estimated dollar impact, so you can see which problems are costing you the most real money. TokenScope also provides specific, evidence-backed recommendations. For example, if it notices you reading the same file three or more times in a session, it flags that as a repeated read. If a single file read consumes over fifteen thousand tokens, it flags that too. It identifies error loops where failed tool calls pile up, and it can spot configured MCP servers that you never actually use. Each finding comes with your own numbers as proof, along with suggested fixes you can paste directly into your configuration files. You can also teach TokenScope about your specific workflow by placing a small configuration file in your project. If your work involves verification steps that look expensive but are intentional, you can tell the tool to suppress certain advice. This keeps the recommendations relevant to how you actually work.