shortit

name	ShortIT
description	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
version	1.0.0
author	Masriyan
tags	["claude-code","token-optimization","cost-reduction","context-engineering","prompt-caching","observability"]

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

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)

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

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

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