# ShortIT > Token-cost reduction for Claude Code — audit where tokens actually go, prune resident context, enforce read/search/output discipline, route work to the right model tier, and prove the savings with before/after measurement from real session transcripts - Skill: `masriyan/shortit` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add masriyan/shortit` - Raw SKILL.md: https://api.skillmd.com/api/skills/masriyan/shortit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Masriyan (https://skillmd.com/u/masriyan) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/masriyan/shortit --- # ShortIT ## Purpose Cut what a Claude Code session costs, and prove the cut with numbers. ShortIT does three things in order: **measure** where tokens actually go in your sessions, **shrink** the two things that dominate the bill, and **verify** the result against a recorded baseline. It replaces guesswork ("be concise") with a diagnosis, because the levers that matter are almost never the ones people reach for first. > **On the 85% target**: reaching it requires all four levers below, and the largest one is usually not behavior. Output-terseness discipline alone lands around 15-25%. Pruning resident context and shortening sessions is where the multiplier lives, because that cost is paid on *every single request*. The scripts here measure your real split rather than assuming one — run them before deciding what to change. --- ## Activation Triggers Use this skill when the user asks about: - Reducing Claude Code token usage, cost, or spend - Why a session is expensive, or where tokens are going - Context window filling up too fast, or frequent compaction - Whether to disconnect MCP servers, trim CLAUDE.md, or restructure skills - Choosing a model tier for cost reasons - Measuring or proving a cost reduction --- ## Prerequisites ```bash python3 --version # 3.9+; standard library only pip install anthropic # optional — only for --exact token counting ``` Scripts read `~/.claude/projects/**/*.jsonl` (local session transcripts) and your `~/.claude` config. No network calls unless `--exact` is passed. --- ## The Cost Model Four numbers explain nearly every Claude Code bill. Know them before optimizing. | Component | Billing | Why it matters | |---|---|---| | **Cached prefix** | 0.1x input rate, **every request** | Cheap per token, enormous in aggregate. A 280K prefix over 2,000 requests is 560M billed tokens. | | **Cache write** | 1.25x (5m TTL) / 2x (1h TTL) | Paid once per prefix change. Anything that mutates the prefix re-pays this. | | **Uncached input** | 1x | New content each turn: your message, tool results. | | **Output** | ~5x input | Never cached. The most expensive token you can generate. | Per-million-token rates: Opus 5 $5 in / $25 out, Sonnet 5 $3 / $15, Haiku 4.5 $1 / $5. Two consequences drive everything below: 1. **The prefix is a recurring charge.** It looks cheap at 0.1x and is the largest line item in most real sessions, because it is multiplied by request count. The prefix has two halves — *static context* (system prompt, MCP tool schemas, CLAUDE.md, skills) which you prune, and *conversation history* which you manage with session hygiene. 2. **Output is 5x input and never cached.** Every unnecessary sentence is charged at the highest rate in the system, with no cache to soften it. --- ## Workflow ### Step 1 — Diagnose (always first) ```bash python3 scripts/token_audit.py --days 30 # where the money went python3 scripts/context_audit.py # what rides every request ``` `token_audit.py` breaks real spend into cached prefix / cache write / uncached input / output, and projects each lever's saving against *your* numbers. `context_audit.py` measures your true static prefix from the first request of each session, then itemizes what's in it from disk. The gap between the two is harness system prompt plus MCP tool schemas. Report the actual numbers to the user before recommending anything. If the diagnosis contradicts the guidance below, follow the diagnosis. ### Step 2 — Record a baseline ```bash python3 scripts/savings_report.py baseline --days 7 ``` Do this **before** changing anything, or there is nothing to prove later. ### Step 3 — Shrink, in order of leverage Apply from `reference/playbook.md`, highest-leverage first. Do not apply all of them blindly — apply the ones the diagnosis pointed at. ### Step 4 — Verify ```bash python3 scripts/savings_report.py compare ``` Read the **per-request** figures, not the totals. Totals move with how much you happened to work; per-request numbers reflect the actual change. --- ## The Four Levers ### Lever 1 — Prune static context (largest recurring multiplier) Everything resident in the prefix is billed on every request for the life of the session. - **Disconnect unused MCP servers.** Each connected server contributes its full tool schema set. A server you are not using in this project is pure overhead on every turn. This is usually the single biggest cut available. - **Cut CLAUDE.md to durable, non-obvious facts.** Delete anything the code, `git log`, or the file tree already states. If Claude could learn it in one `ls`, it does not belong in a file you pay for every turn. - **Keep skill descriptions to one line.** Only the frontmatter `description` is resident; the body loads on demand. Twenty skills with three-line descriptions is a real recurring cost. - **Do not fragment the prefix.** Content that changes mid-session invalidates the cache from that point on and re-pays the write at 1.25x. Keep dynamic values (dates, IDs, status) out of system-level files. ### Lever 2 — Session hygiene (controls prefix growth) The conversation half of the prefix grows every turn and is re-read every turn. A long session is quadratic in cost. - **Scope sessions to one task.** Finish, `/clear`, start the next. A fresh session with a 35K prefix beats a stale one with 280K. - **Delegate search-heavy work to a subagent** when you only need the conclusion. The subagent's file dumps stay out of the main thread's prefix permanently. - **Do not re-read files.** A file already read this session is in context. Re-reading pays for it a second time and inflates the prefix for every remaining turn. ### Lever 3 — Read and search discipline (cuts uncached input) - **Search before reading.** `Grep` for the symbol, then read only the region around the hit. Reading a 2,000-line file to change one function costs the whole file, every turn thereafter. - **Read with `offset`/`limit`** when the target region is known. - **Batch independent tool calls** into a single turn. Each round trip re-reads the entire prefix; three sequential calls pay it three times, one batched turn pays it once. - **Never re-read to verify an edit.** `Edit` fails loudly if it did not apply. - **Prefer targeted commands over dumps.** `rg -c`, `git diff --stat`, `head` — pull the answer, not the haystack. ### Lever 4 — Output discipline and model routing (cuts the 5x tokens) - **Answer, then stop.** No preamble, no recap of what was just shown, no summary of a summary. Output is the most expensive token class and is never cached. - **Skip narration.** "Now I'll check X" costs real money and tells the user nothing they cannot see. - **Do not restate file contents** that were just displayed. - **Route by task difficulty.** Haiku 4.5 is 5x cheaper than Opus 5 on both sides. Mechanical work — renames, formatting, boilerplate, log grepping — does not need Opus. Reserve the top tier for design, debugging, and multi-file reasoning. - **Lower effort for simple work.** Thinking tokens bill as output. `low`/`medium` effort on routine tasks is a direct saving. --- ## Applying ShortIT as Operating Behavior When this skill is active, follow these in your own tool use: 1. Grep before Read. Read with `offset`/`limit` when the region is known. 2. Batch independent tool calls into one turn. 3. Never re-read a file already read this session; never re-read to verify an edit. 4. No preamble, no narration, no recap. State the outcome first. 5. Do not paste back file contents already shown. 6. Prefer `rg -c`, `--stat`, `head` over full dumps. 7. Say when a task would be cheaper on a smaller model or a fresh session. --- ## Honest Limits - **85% is a stack, not a switch.** Behavior discipline is the smallest component. Most of the reduction comes from pruning resident context and keeping sessions short. - **`savings_report.py compare` is a natural experiment, not a controlled one.** A quieter week reads as a saving in the totals. The per-request figures are the defensible ones. - **MCP token estimates are approximate.** Tool schemas are not on disk, so `context_audit.py` infers their cost from the measured/itemized gap rather than reading them. - **Some cuts trade against quality.** Pruning CLAUDE.md too aggressively means re-explaining project context. Routing hard problems to Haiku costs more in retries than it saves. Optimize the recurring overhead first — it is the part with no quality cost at all. --- ## Files ``` ShortIT/ ├── .claude-plugin/ │ ├── marketplace.json marketplace catalog entry │ └── plugin.json plugin manifest ├── SKILL.md this file ├── README.md GitHub landing page ├── scripts/ │ ├── token_audit.py where the money went │ ├── context_audit.py what rides every request │ └── savings_report.py baseline / compare ├── reference/ │ └── playbook.md the full checklist, with rationale ├── docs/ │ ├── INSTALLATION.md install, verify, uninstall │ ├── COST_MODEL.md why sessions cost what they do │ ├── METHODOLOGY.md how it measures, and where it's wrong │ ├── FAQ.md common questions │ └── TROUBLESHOOTING.md when something breaks └── examples/ └── example_usage.md worked end-to-end session ``` ## Reference Material Load these only when the task calls for them — they are not resident context. | File | Use when | |---|---| | `reference/playbook.md` | Applying changes; the ordered checklist with tradeoffs | | `docs/COST_MODEL.md` | The user asks *why* the prefix dominates, or wants the arithmetic | | `docs/METHODOLOGY.md` | The user questions the numbers, or you need to state a confidence level | | `docs/FAQ.md` | Common objections: "is 85% real", "should I disable caching" | | `docs/TROUBLESHOOTING.md` | A script errors or output looks wrong |