Skip to content
Token Optimizer

Setup audit

The setup audit measures every configuration component that loads into context before you type anything, then shows which ones cost the most.

What it does

Section titled “What it does”

Every Claude session opens with a fixed overhead: the global CLAUDE.md, any project CLAUDE.md files, skill metadata, MCP server tool schemas, MEMORY.md, hooks, and settings. Those tokens are spent on every session no matter what you work on.

The audit scans each component individually and estimates its token cost. It then surfaces a calibration gap, the difference between what the audit predicts and what your recent sessions actually started with. A large gap means something is loading that the audit does not account for, or your real sessions are leaner than your current config implies.

A typical unconfigured setup runs 10,000 to 40,000 tokens of overhead before the first message. Setups with many installed skills and verbose MCP server tool lists can exceed 80,000 tokens. The full report breaks that down per component and flags the biggest contributors so you know where to act.

When it runs

Section titled “When it runs”

The audit is manual only. Nothing triggers it automatically. Run it when you want a snapshot of current overhead, after changing your configuration, or before the /token-optimizer skill to pre-load context for the five-phase optimization workflow.

Default state

Section titled “Default state”

The measure.py report and quick commands are available on the shared Python engine; adapter-specific reports can be narrower. OpenCode/OpenClaw use their own TypeScript tools and Pi its extension commands. No feature flag or environment variable enables or disables them.

How to turn off

Section titled “How to turn off”

The audit is a read-only measurement tool. It does not apply configuration fixes. quick does write an automatic drift snapshot and can refresh local analysis state. There is nothing to disable.

Commands

Section titled “Commands”

Run from the scripts directory, or use an absolute path to measure.py.

Terminal window
cd ~/.claude/skills/token-optimizer/scripts


# Full per-component report (default command, runs with no args too)
python3 measure.py report


# Fast scan: overhead total, degradation risk, top offenders
python3 measure.py quick


# Same scan as machine-readable JSON for scripts and CI
python3 measure.py quick --json

On Codex, Hermes, or Copilot, prefix the runtime selector:

Terminal window
TOKEN_OPTIMIZER_RUNTIME=codex python3 measure.py report

What the report covers

Section titled “What the report covers”

  1. CLAUDE.md. Global and project memory files, sized individually so you can see which one dominates.

  2. Skills. Per-skill metadata cost. Every installed skill adds frontmatter that loads each session.

  3. MCP servers. Tool-schema cost per server. Verbose servers with many tools are common top offenders.

  4. MEMORY.md. Auto-memory file size and its overlap with CLAUDE.md.

  5. Hooks and settings. Wiring that runs on each session.

  6. Calibration gap. The predicted-versus-measured delta, so the numbers stay honest against your real session starts.

Defaults and thresholds

Section titled “Defaults and thresholds”
SettingValue
Token estimate basisCalibrated, CJK-aware (about 3.3 chars per token for code)
TriggerManual only
Writes to diskquick auto-saves a drift snapshot; reports do not apply host configuration fixes

Risk rating

Section titled “Risk rating”

None. The audit reads files and reports numbers. It never edits configuration or session content, so there is no fail-open concern and nothing to undo.

Section titled “Related environment variables”

None gate the audit itself. To override the detected context window for the run, see TOKEN_OPTIMIZER_CONTEXT_SIZE and the --context-size flag in the configuration reference.

Platform availability

Section titled “Platform availability”

The full setup-component audit is the Claude Code reference path and is adapted for Codex. Other Python runtimes block these Claude-targeting CLI verbs and use explicit adapter reporting; OpenCode/OpenClaw use their own tools, and Pi a separate extension. A runtime prefix is not a guarantee that every CLAUDE.md/MCP audit exists on that host.

Section titled “Related pages”