Claude Token Optimizer is a command-line tool (cto) that reorganizes a project's Claude Code documentation so that only a small set of files is auto-loaded at session start. It separates four core files (CLAUDE.md, COMMONMISTAKES.md, QUICKSTART.md, ARCHITECTURE_MAP.md) from archived sessions, completed-task history, and topic-based learnings that stay on disk at zero token cost until requested. A .claudeignore file keeps the archived material out of the auto-load set.
The tool measures the token cost of auto-loaded files, audits the structure with 19 structural checks that exit non-zero on errors for CI use, and applies rule-based compression and interactive pruning to CLAUDE.md. Token counts are estimates from the Claude 2 tokenizer. cto init detects the project framework from package.json, requirements.txt, go.mod, composer.json, pom.xml, or Gemfile, and ships pattern files for 13 frameworks (Express, Next.js, Vue, Nuxt, Angular, Django, Rails, NestJS, Laravel, FastAPI/Flask, Go, Spring Boot, and Svelte) listing common mistakes for each.
A set of Claude Code hook templates extends the static structure with runtime monitoring: pre-tool guards that warn or block when auto-loaded files exceed a token threshold, a prompt-submit hook that keyword-matches the user's prompt against docs/learnings/ filenames and injects matching files, write-cost logging, and session snapshots for warm restarts.
Features
- Layered doc structure: four auto-loaded core files, with completions, old sessions, and archived docs excluded via .claudeignore
- Measure and audit: cto measure reports auto-loaded token cost; cto audit runs 19 checks with JSON output and CI-friendly exit codes
- Compress and prune: deterministic rule-based CLAUDE.md compression and interactive section pruning, with --dry-run and a cto diff token delta
- Framework detection: auto-detects the stack from manifest files and writes it into CLAUDE.md; --framework overrides
- Hook templates: PreToolUse token and read guards, PostToolUse write logging, UserPromptSubmit context injection and CLAUDE.md validation, Stop-hook session snapshots
- Context injection: user-prompt-inject-context.sh loads up to 3 matching learnings files (1,500 words max) per prompt, configurable via CTO_* environment variables
- Live dashboard: cto watch refreshes token counts on file change with ASCII bar charts
- Merge-safe updates: cto init appends only missing sections to an existing CLAUDE.md; cto update --content refreshes templates without overwriting custom content
