nadimtuhin/claude-token-optimizer

What it solves

Claude Code often loads excessive amounts of documentation, session notes, and task history at startup, which consumes a significant portion of the context window. This project provides a system to restructure project documentation so that Claude only loads essential files at startup, freeing up thousands of tokens for actual code.

How it works

The tool implements a structured documentation approach using a specific file hierarchy and a .claudeignore file to prevent auto-loading unnecessary docs. It replaces a monolithic documentation file with four core files: CLAUDE.md, COMMON_MISTAKES.md, QUICK_START.md, and ARCHITECTURE_MAP.md.

Key features include:

• Framework-aware initialization: cto init auto-detects the project's framework (e.g., Next.js, Django, Go) and applies relevant best practices and common mistakes.
• Token Measurement: cto measure estimates the token cost of auto-loaded files.
• Maintenance Tools: cto compress and cto prune reduce the size of CLAUDE.md using deterministic rules.
• Context Injection Hooks: Shell scripts that can be integrated into Claude Code hooks to dynamically load topic-specific documentation from docs/learnings/ based on user prompts, ensuring zero token cost for unused files.

Who it’s for

Developers using Claude Code who want to optimize their context window and reduce token usage by moving from auto-loaded documentation to a demand-driven loading system.

Highlights

• Significant Token Reduction: Typical reductions of 83-87% in startup token usage.
• Framework Support: Pre-defined patterns for 13 popular frameworks.
• CI-friendly Audit: cto audit provides health checks for the documentation structure with machine-readable JSON output for CI/CD pipelines.
• Dynamic Context Injection: Hooks that match user prompts to filenames in docs/learnings/ to inject context only when needed.