token-optimization

A guide for using token-optimizer tools while working in a codebase. It explains when to use cached file reading, path-only searching, compact editing, and session optimisation.

In plain words
What is it for?
Use it when inspecting large files, searching a large or unfamiliar project, re-reading files, editing large files, or saving bulky output outside the active context.
Why use it?
Reading and editing large or previously seen files can fill the agent's context with repeated information. The guide helps reduce that repeated context while keeping relevant changes visible.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/ooples/token-optimizer-mcp/token-optimization
Any agent
npx skills add ooples/token-optimizer-mcp --skill token-optimization
Clone the repo
git clone --depth 1 https://github.com/ooples/token-optimizer-mcp

Made for: Claude Code, Codex.

Per session 71 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,061 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00071 $0.01061
Opus 5 $0.00036 $0.00531
Sonnet 5 $0.00014 $0.00212
Haiku 4.5 $0.00007 $0.00106

Measured 2d ago against content hash ac4b52e7029e, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

token-optimization scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

integrations/codex/plugin/skills/token-optimization/SKILL.md · 88 lines

How it starts

The opening of the file, as written. The whole thing — 88 lines — stays where its author put it; the contents beside it link to each section on GitHub.

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.

Read the full file on GitHub · 88 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 88 lines · 71 tokens per session scan A ac4b52e7029e

Subscribe to this mod's changes

token-optimization is a skill published in the GitHub repository ooples/token-optimizer-mcp (501 stars, last pushed 2d ago), licensed MIT. It adds 71 tokens to every session and 1,061 once invoked, about $0.0004 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.