Claude Token Optimizer

Claude rereads everything. Every session. You pay each time.

★ 600+ npm MIT Node 20+

Mine was 11,000 tokens per session. Open 20 sessions a day and that is 220,000 tokens gone before you type a word. That is money, usage limits, and room Claude could have used for your code.

Open a terminal in your project folder and paste each line as is. Inside Claude Code, type ! first, then paste.

0. Keep a copy of your notes, just in case:

cp CLAUDE.md CLAUDE.md.mine

1. See what Claude rereads every session:

npx -y claude-token-optimizer measure

2. Shrink it:

npx -y claude-token-optimizer prune --yes

Old session notes and finished task lists move into side files Claude opens only when needed. You get a line like ✓ Saved ~3414 tokens. Run step 1 again to see your new total. Says "Nothing to prune"? Use the Claude Code prompt below instead.

Rather not type commands? Paste this into Claude Code:

Back up my CLAUDE.md, then set up github.com/nadimtuhin/claude-token-optimizer by following its AGENTS.md. Show me the token count before and after.

Claude reads in tokens. Small pieces of text. Before, every session reread all your project notes, piece by piece.

Now it gets a cheat sheet. A short file at the start. Everything else waits in files Claude opens only when it needs them.

Nothing about how you use Claude changes. Each session just starts lighter.

My project, before and after. Claude still finds the old notes when it needs them. It just stops rereading them every session.

You need Node 20 or newer. Run node -v to check, and install it from nodejs.org if the number is lower.

If it says cto: command not found, put npx -y claude-token-optimizer in front instead of cto.

It rewrites CLAUDE.md and saves the old one as CLAUDE.md.bak. A second run replaces that .bak, so keep your own copy from step 0. cto init (for developers, below) can replace .claudeignore and .claude/*.md in a project with no CLAUDE.md. The exact list of files it writes is in What cto init creates.

Put back the copy you made: cp CLAUDE.md.mine CLAUDE.md. Using git? Run git restore CLAUDE.md, then git clean -n to list the new files, and git clean -fd once you have checked that list.

Everything below is reference. You don't need it to get started.

Install · For AI agents · The numbers · Commands · Hooks · FAQ

Install

The npx lines at the top need no install. Prefer a global cto command? Either of these works:

npm install -g claude-token-optimizer
# or
curl -fsSL https://raw.githubusercontent.com/nadimtuhin/claude-token-optimizer/main/install.sh | bash

Node 20 or newer. init detects your framework from package.json, requirements.txt, go.mod, composer.json, pom.xml, or Gemfile. Pass --framework nextjs, or any name in AGENTS.md, to override.

For AI coding agents

Hand your agent this repo link and one sentence:

Read https://raw.githubusercontent.com/nadimtuhin/claude-token-optimizer/main/AGENTS.md and set up cto in this project.

AGENTS.md lists the non-interactive commands and what each one writes. llms.txt indexes the docs for LLM tools. These run without a TTY and never wait for input:

npx -y claude-token-optimizer init --yes --framework express
npx -y claude-token-optimizer measure
npx -y claude-token-optimizer audit --json     # exits 1 on errors
npx -y claude-token-optimizer prune --yes
npx -y claude-token-optimizer compress --yes

The numbers

On my RedwoodJS project, every session opened by loading about 8,000 tokens of docs, 2,000 of old session notes, and 1,000 of finished task history. cto reduces Claude Code token usage by keeping a short CLAUDE.md and four small reference files loaded, and moving the rest to files read on demand.

The After rows are measured with cto measure right after cto init --yes on an empty project. Adding my own rules and mistakes brought it to about 800.

Measured on my RedwoodJS project. Counts come from the Claude 2 tokenizer, so treat them as estimates.

Everything that moved out is still in the repo. It costs 0 tokens until you ask Claude to read it.

You can do this split by hand. cto does it the same way every time, checks it in CI, and keeps a .bak so the last change can be undone.

What cto init creates

your-project/
  CLAUDE.md                   Claude reads this first
  .claudeignore               keeps old docs out of the session
  .claude/
    COMMON_MISTAKES.md        your top 5 bugs that cost over an hour
    QUICK_START.md            daily commands
    ARCHITECTURE_MAP.md       where things live
    completions/              finished tasks, never auto-loaded
    sessions/                 old session notes, never auto-loaded
  docs/
    INDEX.md
    learnings/                one file per topic, loaded on demand
    archive/                  old docs, never auto-loaded

Abridged. init also creates .claude/templates/ and .claude/sessions/{active,archive}/.

[!WARNING] If you already have a CLAUDE.md, cto init appends the missing sections and leaves the support files alone. Without one, it writes every file above fresh, replacing any .claudeignore or .claude/*.md already there. --force replaces everything with no backup.

Commands

compress, prune, and diff work on CLAUDE.md by default. Point them at any markdown file with --file docs/learnings/testing.md.

[!NOTE] compress and prune support --dry-run and write a .bak of the file as it was before that run. A second run replaces the .bak, so copy the file first if you chain them. compress is lossy: it truncates long lists and strips HTML comments. prune archives completed tasks and session notes under .claude/; empty sections are dropped and come back from the .bak.

Hooks

Claude Code hooks run a script on an event. These templates turn cto from a one-time setup into ongoing enforcement.

cto hooks install --all    # copy templates into .claude/hooks/
cto hooks settings         # print the settings.json block to merge into ~/.claude/settings.json