# Token Optimization

> Use the token-optimizer MCP tools to reduce context/token usage when reading, searching, or editing files, or when the context window is filling up. Trigger when reading large files, re-reading files already seen, searching a big/unknown tree, making edits to large files, or when you need to store bulky output out-of-context.

- Skill: `thedixitjain/token-optimization` (Agent Skill)
- Install (CLI): `npx skillmds add thedixitjain/token-optimization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thedixitjain/token-optimization/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: thedixitjain (https://skillmd.com/u/thedixitjain)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/thedixitjain/token-optimization

---



# Token optimization

This plugin ships a `token-optimizer` MCP server whose tools cut context usage
60–90% via caching, diffing, and compression. Prefer them over the built-in
tools in the situations below. All tools are model-invoked — you must call them;
nothing rewrites the built-in read/grep output automatically.

## When to use which tool

- **`smart_read`** instead of a plain file read when a file is **large**
  (roughly >400 lines / >25 KB) or you have **read it before this session**. It
  caches file content and, on re-reads, returns only a **diff** of what changed
  — often a handful of tokens instead of the whole file. Pass `path`; optionally
  `enableCache`, `diffMode`, `maxSize`, `includeMetadata`.

- **`smart_glob`** instead of a content grep for finding files in a **big or
  unfamiliar tree**. It returns **paths only** (no content) with filtering,
  sorting, and pagination — a fraction of the tokens of listing with content.
  Pass `pattern` (e.g. `src/**/*.ts`) and optionally `cwd`, `extensions`,
  `limit`.

- **`smart_edit`** instead of a raw edit for **large files**: it applies the
  edit and returns a compact unified **diff** rather than echoing the whole
  file. (For very small files a plain edit is fine — smart_edit's diff overhead
  is only worth it once the file is sizeable.)

- **`optimize_session`** / **`get_session_stats`** when the **context window is
  filling up** or after a burst of file operations. `optimize_session`
  batch-compresses prior file operations and stores them out-of-context;
  `get_session_stats` reports tokens saved so far.

- **`get_optimization_report`** when the user asks **how much they've saved**
  (or to show it proactively). Returns total tokens saved, overall savings %,
  approximate cost saved, and a full breakdown **by action, by hook phase, and
  by MCP server**, plus a pre-rendered `formatted` text summary you can display
  as-is.

- **`count_tokens`** to measure how expensive a chunk of text is before you
  decide how to handle it.

## Storing bulky content out of context

- **`optimize_text`** — compress a large text blob under a `key` and keep it in
  the external cache instead of your context; retrieve it later by key. Reports
  `tokensSaved`. Good for logs, large outputs, or reference material you don't
  need inline right now.

- **`compress_text`** — Brotli+base64 compression. **Byte** reduction only:
  the base64 output usually has **more** LLM tokens than the input, so use it
  for **at-rest storage/caching, not for putting back into context.** The tool
  returns `increasesTokens` + a warning when that's the case.

## Rules of thumb

1. Reading a big file or one you've seen before → `smart_read`.
2. Searching a large/unknown tree → `smart_glob` (paths first, read only what
   you need).
3. Editing a large file → `smart_edit`.
4. Context getting tight → `optimize_session`, then continue.
5. Need to stash bulky output → `optimize_text` (by key), not `compress_text`
   into context.
6. Small files/one-off reads → the built-in tools are fine; don't add overhead.

---

**Source:** [`hashgraph-online/awesome-codex-plugins`](https://github.com/hashgraph-online/awesome-codex-plugins) → `plugins/ooples/token-optimizer-mcp/skills/token-optimization/SKILL.md`