"Why read whole file when graph tell you everything?"

TokenCrusher is a codebase intelligence skill that reduces the tokens your AI coding agent consumes by 6.8–49×. It builds a local knowledge graph of your repo and writes compact markdown snapshots that agents read instead of raw source files.

No MCP. No server. No Python. Just a graph, some files, and a skill.

Install

npx tokencrusher install

That's it. TokenCrusher:

1. Detects which AI IDEs you have installed
2. Writes the appropriate config for each (rule file, SKILL.md reference, or autodiscovery file)
3. Builds the initial knowledge graph (~10s for 500 files)
4. Installs a git post-commit hook for automatic incremental updates

How it works

Think of your codebase as a city map. TokenCrusher scans every file and draws connections — "File A calls Function B, File C imports from File D" — and saves that map locally. When your AI needs to make a change, instead of reading the entire city, it just checks the map to find the exact streets involved. It reads only those 2–3 files, not hundreds. That's it. Less reading = fewer tokens = faster, cheaper AI.

Use cases:

• Refactoring a function and want the AI to know exactly what else breaks
• Code reviews where the AI should only read relevant files
• Large repos where the AI keeps reading unrelated files
• Teams wanting to cut AI API costs without changing their workflow

Headline metrics

| Metric | Value | |---|---| | Average token reduction | 6.8× | | Peak reduction (large repos) | 49× | | Incremental update time | <2 seconds | | Initial build (500 files) | ~10 seconds | | IDEs supported | 33+ |

Supported IDEs

| IDE | Method | |---|---| | Claude Code | CLAUDE.md autodiscovery | | Codex CLI | AGENTS.md autodiscovery | | Gemini CLI | GEMINI.md autodiscovery | | Cursor | .cursor/rules/tokencrusher.mdc | | Windsurf | .windsurf/rules/tokencrusher.md | | GitHub Copilot | .github/copilot-instructions.md | | Cline | .clinerules | | Continue | .continue/config.json | | Antigravity | .antigravity/rules.md | | Goose | ~/.config/goose/skills/ | | Warp | ~/.warp/rules/tokencrusher.md | | OpenHands | .openhands/instructions.md | | Roo | .roo/rules/tokencrusher.md | | Amp | .amp/rules.md | | Kiro | .kiro/specs/tokencrusher.md | | Aider | .aider.conf.yml | | + 17 more | AGENTS.md reference |

CLI commands

tokencrusher install                  # detect IDEs, install, build graph
tokencrusher install --only cursor    # install for one IDE
tokencrusher install --dry-run        # preview without writing
tokencrusher install --skip-build     # config only, no graph build
tokencrusher build                    # full graph rebuild
tokencrusher update                   # incremental update (changed files only)
tokencrusher stats                    # print savings to stdout
tokencrusher dashboard                # open dashboard in browser
tokencrusher status                   # graph health summary
tokencrusher clean                    # remove .tokencrusher/
tokencrusher version                  # print version

[!NOTE] Dashboard CORS Restrictions: Opening the dashboard using tokencrusher dashboard loads it via the local file:// protocol. Modern browsers block local file fetches (usage.ndjson and stats.json) due to security CORS policies, which prevents the dashboard from updating in real-time.

To see your real-time savings and exact numbers, use tokencrusher stats directly in your terminal, or host the .tokencrusher folder with a local server (e.g. npx serve .tokencrusher).

Snapshot files

After tokencrusher build, these files appear in .tokencrusher/:

.tokencrusher/
├── index.md              ← full module map (~200 tokens)
├── dashboard.html        ← self-contained savings dashboard
├── stats.json            ← aggregate savings data
├── usage.ndjson          ← per-session usage log
├── impact/
│   └── <module>.md       ← per-module impact perimeter
└── snapshots/
    └── <file>.md         ← per-file structural summary

.tokencrusher/ is gitignored (machine-local). skills/tokencrusher/ is committed.

Language support

Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C, C++

Additional languages: npx tokencrusher install --lang <name>

CI setup

Since .tokencrusher/ is gitignored, CI agents need to build the graph themselves:

# .github/workflows/ci.yml
- name: Build TokenCrusher graph
  run: npx tokencrusher build --skip-build=false

Why TokenCrusher? (Compared to alternatives)

Unlike other codebase intelligence and token optimization tools on the market, TokenCrusher is designed to be as simple, lightweight, and zero-maintenance as possible:

1. Pure Node.js (No Python Hassles)

Many code-mapping tools require you to install Python, run pip or pipx, and configure virtual environments. If you are already working on web or JavaScript projects, this adds unnecessary friction. TokenCrusher is built entirely in JavaScript/Node.js with zero native code dependencies. It installs instantly and runs anywhere Node.js is installed.

2. File-Based & Serverless (No MCP required)

Some alternatives force you to run a background daemon or set up complex Model Context Protocol (MCP) server configurations in your IDE settings. TokenCrusher requires no background servers to drain your CPU or battery. It works entirely through plain, static markdown files in your local .tokencrusher/ folder. Your AI assistant reads these files using its native file-reading capability, meaning it works out-of-the-box in 33+ IDEs with zero protocol setups.

3. Smart Input Optimization (The real cost-saver)

Some tools try to save tokens by teaching the AI to talk in a brief, direct style. While this saves cheap output tokens, it does nothing to prevent the AI from reading large, unrelated source files. TokenCrusher uses a Tree-sitter parser to build a local map of class and function relationships. It does a precise "impact perimeter" analysis to tell the AI exactly which files are affected by a change, saving massive amounts of input tokens (which make up 95%+ of your AI token bill).

4. Automatic Git Sync & Auto-Config

TokenCrusher is set-and-forget. When you install it, it automatically:

• Detects which AI IDEs you have installed and writes the correct rule file for them.
• Installs a Git post-commit hook that updates the code graph in under 2 seconds when you make commits.

Privacy & security

• Zero network calls. No telemetry. No analytics.
• All graph data stays in .tokencrusher/ on your local disk.
• The skill restricts AI to read-only file operations (allowed-tools in SKILL.md).
• No credentials, secrets, or API keys are ever read or stored.

License

MIT — TokenCrusher v1.0. No MCP. Just files, a graph, and a skill.