If you use Claude Code daily, you've felt the friction: asking "What branch am I on?" or "Are there uncommitted changes?" triggers a full API call. The model processes your query, generates a shell command, executes it, and formats the output—burning tokens on something your terminal could answer instantly.
token-ninja solves this. It's an MCP (Model Context Protocol) server that sits between you and Claude Code. When you type a command it recognizes—like git status, docker ps, or npm test—it intercepts the request, runs the command locally, and returns the colored terminal output directly to your chat. Claude never sees it. Zero input tokens, zero output tokens, zero latency for simple ops.
What It Does
token-ninja acts as a smart filter for your Claude Code sessions. It recognizes a growing list of deterministic shell commands and natural language equivalents ("show me recent commits," "what's running on port 3000?").
When you type something it knows:
- Interception: The request never reaches Claude's API.
- Local Execution: The command runs in your shell.
- Direct Return: You see the result in your chat with original terminal colors, plus a small footer showing tokens saved.
Everything else—complex coding questions, file edits, debugging—flows through to Claude untouched. It's purely an optimization layer.
Setup: One Command, Zero Config
The developer prioritized zero-friction installation:
npm install -g token-ninja
That's it. A postinstall hook automatically registers token-ninja as an MCP server with Claude Code, Cursor, and Claude Desktop. It preserves your existing configs, creates backups before modifying any files, and offers a clean uninstall with ninja uninstall.
Safety First: How It Avoids Disaster
Building this wasn't just about command matching. The developer spent more time on safety than classification:
- Double safety checks: Validates both raw input and resolved commands after template expansion.
- Evasion protection: Catches homoglyph attacks, base64-encoded commands, and chained operators.
- Natural language handling: Covers variations like "show recent commits," "what did we push last," and "list last 10 commits" without false positives.
The auto-setup includes backups and dry-run mode specifically because, as the developer notes, "writing to someone's config files during postinstall is a big ask."
Try It Now
Install and test immediately:
npm install -g token-ninja
# Restart Claude Code
# Then try:
# "What branch am I on?"
# "git status"
# "docker ps"
# "npm run test"
You'll see the results appear instantly with a "[token-ninja] Saved ~X tokens" footer. The tool is free, open source, and actively maintained. If it misses a command you use frequently, report it on GitHub—that's how the list grows.
gentic.news Analysis
This tool arrives as Claude Code's ecosystem rapidly expands through MCP. Following recent releases like Distillery 0.4.0 stabilizing its MCP API and Clerk auto-summarizing sessions, token-ninja addresses a fundamental economic pain point: token waste on trivial operations. With Claude Code appearing in 72 articles this week alone (total: 613), developers are clearly seeking ways to optimize their daily usage.
The approach aligns with Anthropic's terminal-first, agentic coding philosophy but adds a pragmatic optimization layer. Unlike tools that require complex configuration, token-ninja's one-command install reflects the low-friction experience Claude Code itself promotes. As token costs remain a consideration for heavy users—especially with Claude Opus 4.6's capabilities—expect more ecosystem tools that optimize the economics of agentic coding.
What You Should Do Differently
Install token-ninja today if you ask Claude operational questions. The savings compound quickly across a workday. After installation, pay attention to which commands trigger it versus which go to Claude—you'll develop an intuitive sense for when you're about to "burn tokens."
Don't change how you work. The tool's value is it requires no behavior modification. Type questions naturally. token-ninja works silently in the background, intercepting what it can.
Contribute command patterns. The tool improves through community feedback. When you notice a simple, deterministic question that still goes to Claude (like "disk space free?"), check if there's an issue or PR on GitHub for it. The classifier improves with real-world usage patterns.
Combine with other MCP servers. token-ninja complements other efficiency tools like Clerk (session summarization) or project-specific MCP servers. Since it only handles shell commands, it won't conflict with other extensions.
Bottom line: This is a straightforward win for daily Claude Code users. One command installs, nothing to configure, and it starts saving tokens immediately on the most common waste sources.
