claude-token-optimizer is a command-line tool (aliased cto) that restructures a project's Claude Code documentation so the assistant loads far fewer tokens at session start. The premise is that Claude Code auto-loads everything at startup — accumulated docs, old session notes, and completed task history — consuming context before any coding begins. The tool reorganizes those files so only a small set of essential documents load automatically while everything else remains available on demand at zero token cost until explicitly requested. It is aimed at developers who maintain a CLAUDE.md and supporting docs and want to reduce that fixed context overhead.
On init, it auto-detects the framework (from package.json, requirements.txt, go.mod, composer.json, pom.xml, or Gemfile) and scaffolds a structure: a lean CLAUDE.md plus a few core files (common mistakes, quick start, architecture map), a .claudeignore to keep old docs from loading, and directories for archived sessions, completed tasks, and topic-based "learnings" that are loaded only when needed. It ships starter patterns for 13 frameworks, each with that framework's common mistakes. init is designed to be non-destructive, appending only missing sections to an existing CLAUDE.md rather than overwriting.
Beyond setup it provides an ongoing maintenance CLI:
- measure — report the current auto-loaded token cost
- audit — run structural health checks, CI-friendly with JSON output and non-zero exit on errors, with an optional --fix
- compress — reduce CLAUDE.md size using deterministic rules (dry-run safe)
- prune — interactively remove stale sections, archiving rather than deleting
- diff — show the token delta before and after compress/prune
- watch — a live token dashboard that refreshes on file change
It also bundles Claude Code hook templates that add active token monitoring and context management — for example warning or blocking when auto-loaded files exceed a threshold, guarding against heavy reads or dangerous bash commands, keyword-matching a prompt to inject the relevant learnings file, and writing per-session snapshots for warm restarts. The reported savings in the author's own project are roughly 11,000 tokens down to about 1,300, with an 83–87% reduction described as typical.
