token-optimization

Token optimization

First inspect the current tool inventory. Use a named token-optimizer MCP tool

only when that exact schema is visible; an installed plugin or MCP config is not

proof that its server registered successfully. If the tool is absent, keep the

native operation available, bound its output, and do not retry an unavailable

schema.

When registered, these tools cache, diff, and bound context. The native hook

refuses a built-in call only after positive registration evidence and injects

applicable graph findings; the active model still makes every MCP tool call.

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.

Live graph

• When wiki_write is visible, call it when you establish a durable,

non-obvious conclusion:

a failed approach and why, a decision and its rejected alternative, or a

command that finally worked. Anchor it to a real file or path#symbol, and

include its concrete evidence, applicability, calibrated confidenceLabel,

scope, and invalidators.

• Perform this semantic harvest yourself while you still hold the reasoning.

Do not delegate it to another model, and do not invent a finding merely to

populate the graph.

• If wiki_write is absent, do not claim semantic harvesting succeeded.
• Applicable findings are injected automatically when their file or command is

touched. Use wiki_read for an explicit lookup.

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).

1. Editing a large file → smart_edit.
2. Context getting tight → optimize_session, then continue.
3. Need to stash bulky output → optimize_text (by key), not compress_text

into context.

1. Small files/one-off reads → the built-in tools are fine; don't add overhead.