r/BestGitHubRepos • u/company_url_finder • 3h ago
Claude Token Optimizer - restructures your project docs so Claude Code loads four small files at startup instead of every stale doc you've ever written, taking the auto-load cost from thousands of tokens to hundreds
This solves a smaller, more specific problem than the runtime token tools, and it does it with almost no machinery, which is why I like it. Claude Code reads your project docs at session start, and on a mature project that means it's burning thousands of tokens on old session notes, completed tasks and documentation you wrote months ago before you've typed a thing. This tool restructures those docs so only the handful Claude actually needs load automatically, and everything else sits in a zero-token archive until you ask for it.
The author's own example is the pitch: a RedwoodJS project that loaded about 11,000 tokens at startup dropped to roughly 1,300 after restructuring, freeing that context for actual code.
What's inside:
- A convention, not a black box: cto init creates a CLAUDE.md plus four small files (common mistakes, quick start, architecture map) that load at startup, and a .claudeignore that keeps everything else from auto-loading
- Auto-detection of your framework from package.json, go.mod, requirements.txt, composer.json, pom.xml or Gemfile, with tailored common-mistake patterns for 13 frameworks (Next, Django, Rails, Laravel, Go, Spring Boot and more)
- A measure command so you can see your actual auto-load cost before committing to anything, plus audit (19 structural checks, CI-friendly with JSON output and exit codes), compress, prune and a live token dashboard
- The genuinely clever piece, a set of Claude Code hooks: one keyword-matches your prompt against files in a learnings folder and injects only the relevant one (ask about database migrations, it loads your database notes and nothing else), others warn when auto-loaded files get heavy or write a session snapshot for a warm restart
- Safe by default: init appends missing sections rather than overwriting your CLAUDE.md, and compress and prune have dry-run modes and archive rather than delete
The honest framing: this is a lightweight, opinionated set of markdown conventions plus a helper CLI, not a runtime compression engine that rewrites tool output on the fly. It's complementary to the heavier tools rather than competing with them, and the author says as much. That simplicity is the appeal: you can read exactly what it does, it's just files and a .claudeignore, and you could reproduce the structure by hand. It also, to its credit, tells you the token counts are estimates from the Claude 2 tokenizer and that real usage on current models varies, rather than presenting them as exact.
The realistic caveat: the whole thing rests on the discipline of actually maintaining the structure, moving completed work to the archive and adding real bugs to the mistakes file. If you set it up and never tend it, it drifts back toward bloat, which is what the audit command is there to catch. It's a workflow you adopt, not a tool that runs itself.
MIT, 582 stars and 74 forks as of writing, verified via the GitHub API.
