claude-token-optimizer: cutting Claude Code's startup context with a docs layout and a cto CLI
Optimize token usage for Claude API calls
At a glance
- What is it?
- The project restructures a repository so Claude Code auto-loads four small files instead of everything, and ships a CLI to measure, compress and audit the result. The README's 11,000 to 1,300 token claim is a self-reported case, and the tokenizer behind the numbers is the Claude 2 one.
- Who is it for?
- Adopt it if you run Claude Code on a repository whose documentation has outgrown its code, and you want a mechanical way to keep the startup context small. Skip it if your CLAUDE.md is already short, or if you need token figures you can defend in a budget review, because the README states the counts come from the Claude 2 tokenizer and vary on current models.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 30 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem claude-token-optimizer targets: Claude Code loads your documentation before your code
Claude Code reads project files at session start. Whatever sits in that auto-loaded set consumes context before the first prompt. The README describes a RedwoodJS project where the startup cost reached 11,000 tokens across 1,783 lines of documentation, old session notes and completed task history. The author frames that as the problem: context spent on stale prose is context unavailable for source code.
The intended user is a developer working in a repository that has accumulated documentation over months, not someone starting a greenfield project. If your CLAUDE.md is a page long and your docs folder is small, the tool has little to remove. The project also assumes Claude Code specifically, since .claudeignore and the .claude/ directory are Claude Code conventions rather than general tooling.
How the layout works: four auto-loaded files, everything else parked at zero cost
The mechanism is a directory convention rather than a runtime process. After setup, the repository contains CLAUDE.md at the root, a .claudeignore file, and a .claude/ directory holding COMMON_MISTAKES.md, QUICK_START.md and ARCHITECTURE_MAP.md. The README's own breakdown assigns roughly 450, 350, 100 and 150 tokens to those four files, about 800 tokens total at session start.
Everything else moves to directories that Claude Code does not read on its own: .claude/completions/ for completed task history, .claude/sessions/ for old work, docs/archive/ for superseded documentation, and docs/learnings/ for topic files you pull in deliberately. The README states these cost zero tokens until you ask for them. That claim depends on Claude Code honoring .claudeignore, which is a Claude Code behavior, not something the package enforces itself.
The CLI is a thin layer over this convention. bin/cto.js is the entry point, src/cli.js is the main module, and templates/ supplies the files that init writes. Dependencies are small: @anthropic-ai/tokenizer for counts, chalk, commander and glob. There is no server, no daemon and no network call at runtime beyond the npm install.
Installing claude-token-optimizer and measuring before you change anything
The package requires Node 20 or newer, per the engines field in package.json. The README gives three install paths. The lightest runs the tool without installing it globally, and the README suggests measuring first so you see the current auto-loaded cost before committing to a restructure.
npx claude-token-optimizer measureThe command prints the auto-loaded token cost. The README notes the counts are estimates from the Claude 2 tokenizer and that actual usage on current models varies, so treat the number as a relative baseline rather than an invoice.
If the number is worth acting on, initialize the structure. The README states the tool auto-detects your framework from package.json, requirements.txt, go.mod, composer.json, pom.xml or Gemfile, and writes the detected framework into the Tech Stack line of CLAUDE.md.
npx claude-token-optimizer initIf detection picks the wrong framework, override it explicitly. The README lists express, nextjs, vue, nuxtjs, angular, django, rails, nestjs, laravel, fastapi, go, spring-boot and svelte as supported values.
cto init --framework nextjsThat last form assumes the global cto alias, which comes from npm install -g claude-token-optimizer or the curl installer the README documents. After init, the README's four follow-up steps are manual: add bugs that took more than an hour to debug to .claude/COMMON_MISTAKES.md, list daily commands in .claude/QUICK_START.md, describe where controllers and routing live in .claude/ARCHITECTURE_MAP.md, and create one file per topic under docs/learnings/.
cto audit, compress and prune: the ongoing maintenance loop
A structure like this decays. New documentation lands in the wrong place, CLAUDE.md grows, and the startup cost creeps back. The CLI addresses that with four commands the README documents as a loop: audit, compress, prune, diff.
cto audit
cto compress
cto prune
cto diffcto audit runs 19 structural checks and exits 1 on errors, which the README presents as CI-friendly. The --fix flag auto-creates missing files and patches .claudeignore. cto compress applies deterministic rules to shrink CLAUDE.md and is described as dry-run safe. cto prune removes stale sections interactively and archives rather than deletes. cto diff reports the token delta between CLAUDE.md and its .bak file, so the saving from compress or prune is visible as a before and after percentage.
The archive-not-delete choice is the right default here. Compression rules operating on a file you wrote by hand can remove a sentence that mattered, and a .bak file is a cheaper safety net than a git revert when you are mid-session. cto watch adds a live dashboard that refreshes on file change with ASCII bar charts, and cto hooks manages Claude Code hook templates. cto update refreshes the CLI itself, while cto update --content refreshes project files from the latest templates and is described as merge-safe, meaning it will not overwrite your custom content.
Where claude-token-optimizer is the wrong tool
The token numbers are the weakest part. The README states the counts come from the Claude 2 tokenizer and that actual usage on current models varies. Claude 2 is not the model Claude Code runs on, so the 11,000 to 1,300 figure is a self-reported result from the author's RedwoodJS project measured with a mismatched tokenizer. The relative direction is plausible; the absolute saving is not something you can put in a budget.
The 90% reduction headline also describes one repository. A project whose CLAUDE.md is already 200 tokens has almost nothing to cut, and the four-file structure adds a small fixed cost of its own. The tool is a documentation organizer, not a prompt compressor. It does not summarize your source code, cache model responses, or change how Claude Code chunks a file. If your token spend comes from large source files being read during a task, this package does nothing about it.
There is also a dependency on Claude Code honoring .claudeignore. The README treats zero-cost parked files as a property of the layout, but the enforcement lives in the client. If that behavior changes, the parked directories stop being free and the arithmetic in the README no longer holds. Nothing in the repository can guarantee it.
Finally, the README does not document rollback. Since init writes files into your project, and the README does not describe an uninstall or revert command, the practical path back is version control. Run it on a clean working tree.
How it compares with a hand-written CLAUDE.md
The real alternative is doing this yourself: write a short CLAUDE.md, keep a .claudeignore, and move old notes into an archive folder by hand. That costs nothing, has no Node version requirement, and gives you full control over what the four files say. Many teams already do a rough version of it.
The difference is the maintenance loop. A hand-written CLAUDE.md drifts because nobody measures it. claude-token-optimizer supplies a number (cto measure), a rule-based shrink (cto compress), an archive step (cto prune) and a delta report (cto diff), plus a 19-check audit that can fail a CI job. That is the actual product: not the directory layout, which you could copy from the README in ten minutes, but the recurring check that tells you the layout has drifted.
The framework examples are a secondary differentiator. The repository ships 13 files under examples/, one per framework, each with the top 5 critical mistakes for that stack. These are static markdown, not generated analysis, so their value depends on whether the listed mistakes match the ones you actually hit.
Editorial conclusion
Adopt it if you run Claude Code on a repository whose documentation has outgrown its code, and you want a mechanical way to keep the startup context small. Skip it if your CLAUDE.md is already short, or if you need token figures you can defend in a budget review, because the README states the counts come from the Claude 2 tokenizer and vary on current models. Before trusting it, run npx claude-token-optimizer measure on a copy of the repository, then cto audit after init to see which of the 19 structural checks fail on your layout. The tool never deletes: cto prune archives, so the first migration is reversible.
Frequently asked questions
How does Claude AI work with tokens in claude-token-optimizer?
The package counts tokens with the @anthropic-ai/tokenizer dependency, and the README states the counts are estimates from the Claude 2 tokenizer whose actual usage on current models varies. cto measure reports the auto-loaded cost, and cto diff reports the delta between CLAUDE.md and its .bak file.
How do I maximize Claude Code tokens with claude-token-optimizer?
The README's approach is to keep only four files auto-loaded (CLAUDE.md, COMMON_MISTAKES.md, QUICK_START.md, ARCHITECTURE_MAP.md) and park everything else in .claude/completions/, .claude/sessions/, docs/archive/ and docs/learnings/, then run cto compress and cto prune as the files grow.
Is Claude Code more token efficient after running claude-token-optimizer?
The README reports a single case dropping from 11,000 to 1,300 tokens, which it attributes to loading roughly 800 tokens across four files at session start. That figure is self-reported and measured with the Claude 2 tokenizer, so it is a direction rather than a guarantee.
Community notes