Claude Token Optimizer: fewer tokens at startup
Claude Token Optimizer
The cto utility counts the tokens Claude Code loads at session start and shrinks CLAUDE.md into a short cheat sheet.
- 636 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The prune, compress and init commands rewrite CLAUDE.md and create files in .claude and docs, and the --force flag replaces everything with no backup
- Hook templates installed by cto hooks install interfere with the agent: they block file reads and Bash commands and inject text into prompts
- Running through npx -y executes the package code from npm, and the curl install pipes a script from GitHub straight into the shell
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/claude-token-optimizerDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The prune, compress and init commands rewrite CLAUDE.md and create files in .claude and docs, and the --force flag replaces everything with no backup
- Hook templates installed by cto hooks install interfere with the agent: they block file reads and Bash commands and inject text into prompts
- Running through npx -y executes the package code from npm, and the curl install pipes a script from GitHub straight into the shell
This is third-party code. Review the repository files before installing.
What it does
Claude Code rereads your project notes at the start of every session, and the longer they are, the more tokens go before the first question. The cto utility from the claude-token-optimizer package cuts that cost. It leaves a short cheat sheet in `CLAUDE.md` and moves the rest into files Claude opens only when needed. On the author's RedwoodJS project, startup loading dropped from about 11 thousand tokens to 800. The first two commands are enough to start. `npx -y claude-token-optimizer measure` shows, file by file, how many tokens load at startup. `npx -y claude-token-optimizer prune --yes` moves finished tasks and old session notes into side files inside `.claude`. For a project from scratch there is `cto init`: it detects the framework from `package.json`, `go.mod`, `composer.json` and other files and creates a set of reference files and `.claudeignore`. For ongoing control there is `cto audit` with 19 structural checks, `cto compress` to shrink markdown by rules without a model, `cto diff`, the live `cto watch` dashboard and `cto hooks` with 12 hook templates. The hooks warn about a bloated context, block reads of lock files and binaries and inject only the relevant files from `docs/learnings` into a prompt.
Who it is for. For people who use Claude Code every day, hit usage limits and notice that CLAUDE.md and project docs have grown too large.
Good fit when
- Claude Code limits run out faster than expected and `CLAUDE.md` has grown to hundreds of lines
- You want to know how many tokens load at session start and which files carry most of the weight
- The project has accumulated notes from past sessions and lists of finished tasks that Claude reads for nothing
- You need a context structure check in CI: `cto audit --json` exits with code 1 on errors
- You want Claude to pull reference notes for the topic of a request from `docs/learnings` rather than read every file
Not a fit when
- Token spend does not come from session startup: the utility trims only what loads upfront and leaves command output and file reads during work alone
- You need cost reports from Claude Code logs: separate tracking tools exist for that
- Your `CLAUDE.md` is already short and tidy: the gain will be small
- You need exact token counts: the counter uses the Claude 2 tokenizer and gives an estimate
Example request
Back up CLAUDE.md, measure startup tokens with cto and show how much could be saved before changing anything.Limitations
It needs Node.js 20 or newer. The token counter uses the Claude 2 tokenizer, so the numbers suit before-and-after comparison and cannot be matched against a bill. Counting and the `.claudeignore` rules target Claude Code, and other agents simply read the resulting markdown.
`cto compress` is lossy: it truncates long lists and strips HTML comments. `cto prune` and `cto compress` save the previous file as `.bak`, but a second run overwrites that copy, so copy the file yourself before chaining commands. If `CLAUDE.md` already exists, `cto init` only appends missing sections, and without it the command replaces any existing `.claudeignore` and `.claude/*.md`. The `--force` flag replaces everything with no backup.
Whether npm is reachable from Russia was not checked for this card.
How to disable. Put back your saved copy with `cp CLAUDE.md.mine CLAUDE.md`, or in a git project run `git restore CLAUDE.md`. `git clean -n` lists the new files and `git clean -fd` deletes them once you have checked the list. If you installed hooks, remove the cto block from `settings.json` and the `.claude/hooks` folder. A global install is removed with `npm uninstall -g claude-token-optimizer`.
FAQ
How do I reduce Claude Code token usage with cto?
Copy your notes with `cp CLAUDE.md CLAUDE.md.mine`, check the startup load with `npx -y claude-token-optimizer measure`, then run `npx -y claude-token-optimizer prune --yes`. Finished tasks and old notes move into side files, and a second `measure` shows the new total. If `prune` says there is nothing to trim, the author suggests handing Claude Code the repository link and AGENTS.md.
What does cto change in my files?
It rewrites `CLAUDE.md` and saves the previous version as `CLAUDE.md.bak`. The `cto init` command creates `.claudeignore`, a `.claude` folder with three reference files and `docs/INDEX.md`, and when `CLAUDE.md` is absent it replaces any `.claudeignore` and `.claude/*.md` already there.
How do I undo what cto did?
Put back the copy you made before running with `cp CLAUDE.md.mine CLAUDE.md`. In a git repository `git restore CLAUDE.md` works, and `git clean -n` lists the new files. Do not rely on the `.bak` file: the next run overwrites it.
Does cto work with Cursor and Codex?
The output is plain markdown files that any agent can read. Token counting and the `.claudeignore` rules target Claude Code.
How does cto detect a project's framework?
The `cto init` command looks at `package.json`, `requirements.txt`, `go.mod`, `composer.json`, `pom.xml` and `Gemfile`. The `--framework nextjs` flag or another name from AGENTS.md sets it by hand. The examples folder holds starters for Express, Next.js, Vue, Django, Rails, Laravel, Spring Boot and more.
Discussion
No questions or reviews yet.
Related
CLI toolsA Claude Code plugin that generates and maintains CLAUDE.md: a 0 to 100 quality score, a 150-line cap and stale reference checks
A debugging tool for Claude Code that reads the session logs already saved on disk and shows exact file paths, diffs, model thinking and a category-by-category
A starter kit for Claude Code: a CLAUDE.md memory-bank template with ready hooks, subagents and skills you copy into your project
A Go CLI proxy that shrinks git, test and build output with YAML filters before it reaches the agent. The author estimates 60-90% token savings
A set of Claude Code mods: status lines above the prompt, a guard against risky commands and a few small games
A Claude Code plugin: 39 commands for PRs, review, commits and specs, nine expert roles and hooks, in eight language versions
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Claude Token Optimizer: fewer tokens at startup (this entry) | no | 636 | |
| Token Optimizer | no | 2,780 | a plugin for Claude Code and Codex that cuts wasted tokens and keeps work across sessions |
| ccusage | no | 19,238 | token and cost reports from local logs, cuts nothing |
README in short
The document is built around two quick-start lines and an explanation of what happened to the tokens. Next come help blocks with common errors, answers about overwriting and rollback, and a developer reference: installation, agent mode, a before-and-after table, the file layout after init, and the lists of commands and hook templates. The end lists third-party token-saving tools that `cto companions` shows, rules for keeping the context small and answers to common questions.