How to cut Claude Code context cost

Ranked by measured impact. Every number links to the run that produced it.

what actually helps

1. 01

   Keep a SessionStart hook under 10,000 UTF-16 code units

   10,016 vs 2,172

   saves the 78% of your payload that otherwise never arrives

   Anthropic caps SessionStart hook output at 10,000 and documents it twice. Below the cap 10,016 tokens of context arrive, identical in all four rounds; above it 2,172 to 2,181. The arms do not overlap, so about 78 percent of what you sent is not delivered. It is not destroyed: the payload is written to a file the model must spend a tool call to read, which is why a plugin that injects standing instructions can silently stop delivering most of them. The cap counts UTF-16 code units rather than characters, so every emoji counts twice. obra/superpowers, at 3,334 bytes, is comfortably under and was inlined in every round. See the measurement.

2. 02

   Ask for the whole task in one prompt, not step by step

   2.64x

   saves 2.6x on a three-step task

   Cost tracks round trips, not sessions. The same three steps cost 103,828 tokens asked at once and 274,436 asked one at a time in the same session. A fit across 30 runs gives 23,116 tokens per turn with no measurable fixed cost per run. See the measurement.

3. 03

   Batch your tool calls

   1.97x

   saves up to 2x the whole session

   Each tool round trip re-sends the entire conversation. Three files read in one batch cost 121,732 tokens; the same three read one at a time cost 240,073. See the measurement.

4. 04

   Leave MCP tool search on

   41x

   saves 15,069 tokens minimum

   Turning it off costs 15,069 tokens with zero MCP servers connected, because Claude Code defers its own built-in tools through the same path. THIS FIGURE IS RE-MEASURED WITH THE STARTUP FLOOR, not with the post below, and the post predates it: the zero-server delta read 17,805 on 2.1.231, 17,664 on 2.1.232, dropped to 14,644 on 2.1.233, and has read 15,069 on 2.1.236, 2.1.238, 2.1.241 and 2.1.246, with a single release out of line at 15,251 on 2.1.243 that reverted, and 15,193 on 2.1.251. The FLOOR underneath it, however, fell hard on 2.1.251: 22,801 to 17,207 tokens, 24.5 percent, the largest move recorded here. So the 17 percent drop the older write-up describes did not hold. The 200-tool figures are a separate measurement and have NOW been re-measured on 2.1.246: the difference between 3,210 and 130,410 tokens, byte-identical to 2.1.238 in every one of the six cells, deferred and loaded, at 5, 50 and 200 tools, each single-valued across four rounds with zero spread. See the measurement.

5. 05

   Count your subagent definitions, not your plugins

   2.04x

   saves 51 tokens per definition, and it never falls

   Skills and slash commands both cost about 40 tokens each and then collapse to under 6 once you pass a few hundred. Subagent definitions do not: 51 tokens each at 10, at 200 and at 400. That makes 400 of them cost 20,404 to 20,602 tokens against 9,989 to 10,187 for the same number of commands, and it is the one part of a plugin where the raw count is the thing that matters. See the measurement.

6. 06

   Measure your own skill pack; the documented ~100 tokens a skill is not a ceiling

   193%

   saves up to two thirds of what the figure implies

   Anthropic documents ~100 tokens per Skill for the metadata loaded at startup. Measured across the three trending packs where a measurement is reliable, per-skill cost ran 34.1 to 95.9 and every one came in under it. It is NOT a ceiling, though: this site later measured the example-skills pack Anthropic itself ships, twelve skills with 288-character descriptions, at 102 per skill, which is above the documented figure. So ~100 over-predicts for most packs and under-predicts for at least one, which is the reason to measure rather than assume in either direction. The figure over-predicts by 4% on one pack and 193% on another, and the size of the miss does not order by description length: the closest fit is the pack with the middle description length. Nothing measured predicts which end you will land on. google/skills is 9,020 tokens where the documented figure implies 11,100. See the measurement.

7. 07

   Price a skill pack before you install it

   9,020

   saves up to 9,020 tokens per session

   Agent Skill collections are what GitHub is trending, and the cost is silent. Installed and measured on 2.1.233: google/skills is 9,020 tokens on every session for 111 skills, addyosmani/agent-skills 2,302 for 24, mattpocock/skills 852 for the 25 it ships. Per skill that is 34.1 to 95.9, and it does not order by description length: the pack with the longest descriptions is not the dearest. Check the plugin manifest before pricing a pack you did not write, because the number of SKILL.md files in a repository is not the number you get: Matt Pocock ships 25 of 35, and this site published the wrong one before correcting it. The rate this site published landed within 8% on one pack and 63% and 64% high on the other two, so install it and measure rather than multiplying. See the measurement.

8. 08

   Move reference material out of CLAUDE.md and into skills

   1,845x

   saves 0.26 to 0.42 tokens per byte moved, depending on how the file is written

   CLAUDE.md is charged on every session and again on every tool round trip. A skill body is charged only when invoked. The same 28KB costs 7,379 tokens as CLAUDE.md and 4 tokens as a skill body. The 0.26 rate was fitted on flowing English prose; a real 2,357-byte markdown-structured CLAUDE.md measured on 2026-08-24 cost 0.417 tokens per byte at the mode, over 15 rounds and 120 runs. Reference material is usually the structured kind, headers and bullets and tables, so the saving from moving it is more likely near the top of that range than the bottom. One file does not re-fit a curve fitted from 2KB to 28KB, so the range is published rather than the rate replaced. See the measurement.

9. 09

   Trim CLAUDE.md for the window, not for the bill

   20x

   saves context on every turn, but almost no money after turn 2

   An 18KB CLAUDE.md adds 4,967 tokens to every turn and never decays, so the window cost is permanent and worth managing. The money is not: the same tokens bill as a cache write on turns 1 and 2 at $0.04966 and $0.04967, and as a cache read from turn 3 at $0.00248, about a 20x drop. 95% of a four-turn session cost is spent before turn 3. The exceptions are the two rows either side of this one: editing the file rebuilds the cache, and every parallel subagent re-pays the configuration. See the measurement.

10. 10

    Batch your config edits

    14.6x

    saves 47,544 tokens per edit avoided

    Any change to CLAUDE.md or your skills invalidates the cached prefix, and the next run rebuilds it. A one-character edit costs the same as a rewrite. Ten separate tweaks cost ten rebuilds. See the measurement.

11. 11

    Capture screenshots at logical resolution, not retina

    1.69x

    saves 41% of the image cost, for free

    This used to read "downscale to 2000px", which does nothing: anything over 2000px on the long edge is resized before it is sent, so the client already discards those pixels for you and capping the width yourself saves zero. The saving that is real comes from the CAPTURE, not the resize. A retina capture of a 1470x956 screen costs 3,132 tokens; the same screen captured logically costs 1,850, so you pay 59 percent for the same picture. On macOS that is the difference between a default screenshot on a retina display and one taken at logical resolution. See the measurement.

12. 12

    Front-load discovery, then read in one batch

    58,851

    saves one whole context per call avoided

    A round trip costs roughly your entire current context regardless of what it returns. Reading a 6-byte file cost 58,851 tokens. Grep once to find the files, then read them together. See the measurement.

13. 13

    Keep your fan-out narrow, and trim CLAUDE.md before you widen it

    110x

    saves 20,581 to 28,504 tokens per agent you do not spawn

    Each parallel subagent costs 20,581 to 28,504 tokens before doing anything on 2.1.238, against about 186 to do the same trivial work inline. It is a range rather than a flat figure because a four-way fan-out runs in one of two modes, six parent turns or seven, which the caller does not control: the dearest six-turn run and the cheapest seven-turn run are 23,389 tokens apart with nothing in between (that gap is the 2.1.232 measurement, not 2.1.238). Worse, every subagent re-pays for your configuration and then some: on a machine carrying 37,504 tokens of it, the cost per agent rose to 112,419, about twice that configuration rather than once. Trimming CLAUDE.md is worth roughly twice as much again as your fan-out is wide. See the measurement.

14. 14

    Count a non-Latin skill description in tokens, not characters, against the 1,024 cap

    0.363-0.482 vs 0.887-1.048

    saves roughly half your description budget on a CJK description

    Nine skills were installed one at a time on 2.1.247, four rounds each, against a floor re-measured in the same round. Per description CHARACTER, descriptions containing no CJK cost 0.363 to 0.482 tokens and majority-Chinese ones cost 0.887 to 1.048. The arms do not overlap, and the two character-length ranges overlap (English 198 to 485, Chinese 167 to 518), so length is not carrying the difference. The qualification that matters: per BYTE of UTF-8 the arms OVERLAP, 0.363 to 0.482 against 0.459 to 0.513. A Chinese character is about 2.3 bytes, so most of the per-character gap is the unit rather than the tokeniser mistreating Chinese. It still bites in practice, because the 1,024-character description cap counts characters and this site prices skills per character: a Chinese description hits that cap having spent roughly twice the tokens an English one would. The published model of 39 tokens plus 0.276 per character lands within 5 percent on the English arm and 2.48x under on the Chinese arm, and six of the nine cells sit outside the 30 to 300 character range the model was declared valid for. See the measurement.

15. 15

    Price a skill by what it DOES when it fires, not by what it costs sitting installed

    6 of 6 vs 0 of 6

    saves up to 100,000 tokens on a single task

    JetBrains go-modern-guidelines installs one skill. Sitting there unfired it costs tens of tokens, too small for this machine to resolve cleanly. When it fires it shells out to a CLI, and on 2.1.247 the same Go task cost 45,582 to 45,960 tokens without it and 146,181 to 146,872 with it, roughly 3.2x, arms not overlapping across ten paired rounds on two tasks. The skill does not inject 100,000 tokens: it adds tool round trips, and each tool call re-sends the whole conversation. It is worth knowing what the 3.2x buys. On a task with no modern idiom to apply it bought nothing, producing code identical apart from one word of a doc comment. On a task the tool own ruleset covers it delivered every time: the arm without the skill wrote the pre-1.21 sort.Slice in 6 of 6 runs and the arm with it wrote slices.SortFunc with cmp.Compare in 6 of 6, with no run going the other way. The skill description fires on any Go edit, so the cost is paid whether or not there is anything to fix. See the measurement.

16. 16

    Price an always-on output-style hook at what it injects every session, not once

    1,475 per session

    saves 1,475 tokens per session if you decide it is not worth it

    ayghri/i-have-adhd (25,853 stars, MIT) offers an optional always-on mode: a SessionStart hook that injects its full ruleset into every session. Measured on 2.1.251 across twelve paired rounds, that costs 1,475 tokens every session, single-valued in both arms. The payload is 6,598 UTF-16 units, 66 percent of the 10,000-unit cap this site measured, so it arrives intact rather than being silently truncated, and the 1,475 figure confirms that independently because 6,598 units of prose predicts about 1,478 tokens. Does it work? Replies are shorter, median 855 characters against 712, roughly 0.83x. But the arms OVERLAP, so that is a median difference across twelve rounds and not a per-run effect you can count on. At four rounds the arms did not overlap and the answer would have looked stronger than it is. Length was measured; quality was not. See the measurement.

17. 17

    Count what a skill pack MANIFEST installs, not the SKILL.md files on disk

    898 on disk, 286 installed

    saves a 3.1x error in your own estimate before you measure anything

    affaan-m/ECC (244,921 stars, MIT) has 898 SKILL.md files on disk. 519 of them are documentation copies, 43 are for another harness and 11 for a third; the Claude Code manifest declares only ./skills/, which holds 286. Estimating from the disk count would have been 3.1x high before any measurement. Measured on 2.1.251 across twelve pooled rounds, the 286 that actually install cost 9,210 tokens at startup, 32.2 per skill, the same value in every round. Worth knowing what that means for the estimate on this page: the skills curve interpolates to 8,635 at 286, so it is 6.7 percent out here, while the same curve was 5.15x low on a real 817-skill pack. The packs differ in description length, median 258 against 396, and no cause is established for the gap. See the measurement.

18. 18

    Extract PDFs to markdown, not plain text, if the document has tables

    40 table rows vs 0

    saves the column-to-value association, for about 9 percent more tokens

    Feeding a PDF to a model means extracting text first, and the extractor decides what survives. Measured on 2.1.251 across six paired rounds on the same 10-page PDF: pdftotext produced 4,454 characters with zero markdown headings and zero table rows, and firecrawl pdf-inspector produced 4,795 characters with 60 headings and 40 table rows. The decisive case is a colour table. pdf-inspector reconstructs it as pipe-delimited rows so each hex code sits under its colour name; pdftotext emits the names and the hex codes as separate disconnected lines and which belongs to which is gone. The structure costs 1,986 tokens against 2,162, so 176 extra or 8.9 percent, and the per-byte rates are nearly identical at 0.4459 against 0.4509, meaning you pay for the extra characters rather than for markdown tokenising badly. It was also about 5x faster than pdftotext on this file. What is NOT measured: whether a model actually answers better from the structured version. See the measurement.

19. 19

    Price a long skill description at 0.363 to 0.482 tokens a character, not 0.276

    159 tokens at 398 chars

    saves a 16 percent under-budget on every description past 300 characters

    This site publishes 0.276 tokens per description character and prints the range it was fitted on, 30 to 300, right next to it. Real descriptions run longer than that. book-to-skill (27,490 stars, MIT) ships a 398-character one, and installing it costs 159 tokens a session, measured on 2.1.251 across six paired rounds against a floor re-measured in the same round, with the same figure from all three arms. Extending 0.276 past its bound predicts 134. The band already measured on five real English descriptions, each installed alone in an empty project, is 0.363 to 0.482 per character, which predicts 144 to 192 and brackets the measurement; its own rate is 0.400. One point cannot fit a rate and none is claimed, but it is enough to say which of two published answers holds out there. The /cost/ page now carries the bound and the band. A description in Chinese costs roughly twice as much per character again. See the measurement.

20. 20

    Budget parallel subagents from a current measurement, not from the release that made your session cheaper

    20,751 to 21,326 a subagent

    saves the false expectation that a 23 percent floor drop applies to fan-out

    Between 2.1.238 and 2.1.251 the startup floor fell about 23 percent. Measured in the SAME eight rounds by the same harness, the trivial isolated cell went from 21,890 to 22,787 down to 17,048 in every single round with zero spread. The per-subagent slope did not follow: at the modal six parent turns it is 20,751 to 21,326 tokens an agent, against 20,581 measured on 2.1.238 at the same turn condition, so it is unchanged to within about one percent and if anything slightly up. Forty runs, none failed, every arrival control held, all on one identical working directory so no difference carries a path term. No point estimate is published because no context value repeats across rounds in either fan-out cell and guarded mode refuses; that is a property of these cells, not of the round count. What this does NOT say: the loaded arm was not run, so the configuration multiplier still rests on 2.1.238, and only the six-turn condition cleared the four-run floor, so nothing here speaks to the seven- and ten-turn conditions the older corpus published. See the measurement.

21. 21

    Write a deny rule with two leading slashes for an absolute path, or none at all

    6 of 6 relative shapes block

    saves a rule you believe protects a secret and does not

    Measured on 2.1.251 across forty runs, ten rule shapes, four rounds each, scored from the session transcript rather than from whether the secret appeared in the reply. Every relative shape blocks the read 4 of 4: ./.env, .env, **/.env, *.env, ./*.env and ./.env*. The documented absolute form, two leading slashes, also blocks 4 of 4. A rule with ONE leading slash does not block in any round, and the read comes back with no error. That is documented: the vendor states in a Warning box that a single leading slash anchors at the settings source rather than the filesystem root, so the rule resolves to a path under your project that does not exist. The fix is one character. Also measured, and worth knowing before you trust a rule: naming the same file through /tmp, which on macOS is a symlink to the real system temporary directory, did not block either. What this does NOT cover: Edit and Write rules, a .env anywhere but the project root, and user or managed settings scopes, where the same rule anchors somewhere else by design. See the measurement.

what does not help

• Add a .claudeignore so Claude Code stops reading node_modules

  The file is not documented and does not block anything: asked to read a file inside a directory it excludes, the model returned the contents 3 times out of 3. There is also nothing to save. A project carrying 7.9MB and 1,960 extra files cost 2 more tokens at startup, and node_modules was never opened in 24 runs. See the measurement.

• Clear the context between tasks to keep costs down

  True for unrelated work, which is what the documentation actually says. Applied to related steps it reversed: clearing cost more in 10 of 10 paired rounds, and the session that was never cleared got cheaper as it went, its third step costing 25,312 tokens less than its own first. See the measurement.

• Plan mode is the cheaper way to work

  Measured twice, it cost 2.18x on a task with one right answer and 2.27x on an open-ended one, with no overlap either time, and both arms produced work that passed every check. Planning did make the execution cheaper, but only on the specified task, and the plan cost about five times the saving it bought. See the measurement.

• Long conversations get expensive as context grows

  A continued turn writes only what is new: exactly 293 tokens per trivial turn, with the rest served from cache. Over six turns the context grew 1,465 tokens and cost rose 2%. Tool round trips multiply your context; conversation turns do not. See the measurement.

• Leaving --effort high is quietly expensive

  Effort does not change your context size at all, and on a trivial task output was 4 tokens at every level including max. The only cost is a one-off 40,054-token cache write the first time you use each level. See the measurement.

• Delegating to a subagent keeps your context small for free

  It costs 1.72x the total tokens and saves only what the subagent absorbed: 8,175 tokens on a three-file read. It pays back after about 11 more round trips, so delegating a small task late in a session is worse than doing it inline. See the measurement.

• A big CLAUDE.md makes Claude slower

  No detectable effect. A 28KB CLAUDE.md was slower in 13 of 20 paired runs, a sign test p of 0.263. Run-to-run variance on identical configs ran from 1,527 to 8,337 ms and swamps it. See the measurement.

• Keep to four to six plugins and you will be fine

  A rule about the wrong quantity. A plugin is not one thing, and its parts price differently: a skill or a slash command costs about 40 tokens and collapses to under 6 past a few hundred, while a subagent definition costs 51 and never gets cheaper at any count measured. So 400 commands cost 9,989 to 10,187 tokens and 400 subagent definitions cost 20,404 to 20,602. Count listing entries, not plugins, and count your subagent definitions separately. See the measurement.

• Long skill bodies are expensive

  Forty skills carrying 28,000-byte bodies cost 1,576 tokens against 1,574 for 200-byte ones: two tokens across a 140x range. The body loads only when the skill is invoked, so long reference material is effectively free until used. Re-measured on 2.1.233, where all three body sizes returned the same value in all four rounds, making this the cleanest run of it on record. See the measurement.

• Installing lots of skills bloats your context

  Half right, and which half depends on your setup. On a clean project a skill costs 39 tokens until you have about 200, then 3.9 after about 400: forty cost 1,570 and a thousand cost 11,711. On a machine with its own configuration loaded, forty cost 152, a 10.2x gap from the flag alone. Either way it is small against a 22,643-token floor, but 1.5 each is what a configured machine measures, not what a skill costs. See the measurement.

• Long skill descriptions cost more context

  Not a myth below about 200 skills, where a description is nearly the whole cost of one: 0.276 tokens per character up to 300 characters, so 40 skills at 300 characters cost 3,856 tokens against 856 at 30. Past the collapse it stops being charged entirely, and 600 skills cost the same whether their descriptions are 30 or 300 characters. Write descriptions long enough to match on, and know which side you are on. There is a separate ceiling on how long that can usefully be: text past about 1,530 characters is cut out of the listing entirely, against a documented cap of 1,536 that you can raise with skillListingMaxDescChars. See the measurement.

• Compressing an image before sending it saves context

  Cost tracks pixel dimensions and nothing else. The same 1568x1568 image cost 3,135 tokens at 623 bytes and 3,140 tokens at 2MB, a 3,366x file-size range for a 5-token difference. Resize instead of compressing. See the measurement.

• A cold cache makes the next run slower

  It makes it about 15x more expensive, but four paired runs found no latency penalty. Preliminary, and worth treating as such, but it points away from the intuition. See the measurement.

• Keep CLAUDE.md under about 150 rules or it starts ignoring them

  The 150 figure comes from a benchmark that scores 500 keyword instructions all at once on a writing task, which is not what a CLAUDE.md is. Laddered from 2 to 500 rules, a rule at the top of the file and a rule buried at the very bottom were both obeyed in 180 checks out of 180, while the same file with those rules deleted scored zero. What 500 rules cost is 23,427 tokens of context, not obedience. See the measurement.

• Make Claude Code less verbose to cut your token bill

  A terseness rule really does halve the output, 4,733 characters down to 1,969 across 30 runs. It saved 6.8%. Output is only 1.45% of billed tokens and 10.2% of cost, so a tenth of the bill is the whole budget that lever has, and collecting all of it would mean emitting nothing. The 40 to 70 percent figure is not reachable by this route. See the measurement.

• The five-minute cache expiry is draining your quota

  Not on a subscription, where Claude Code asks for the one-hour cache and an eight-minute break costs 39 tokens on the next turn rather than a rebuild. But that protection is not free: one-hour writes bill at 2x list against 1.25x, and forcing the five-minute TTL made a three-turn session 7.6% cheaper, writing 50% more cache tokens and still costing less. Which way it goes depends on how often you actually break for more than five minutes. See the measurement.

• Set CLAUDE_CODE_FORK_SUBAGENT=1 to cut parallel subagent costs by 90%

  On 28 runs it went the other way: total context rose 38% on a cold session and 66% on a warm one, and cost rose 8% and 16%, with every flag-on run above every flag-off run. Cache creation, the thing it should remove, moved 1.7 to 5.4%. A forked child inherits the parent conversation, so the prefix is cheap to read and there is far more of it. See the measurement.

• Rewrite your CLAUDE.md in English, or in Chinese, to save tokens

  Neither direction is worth doing for cost. One translation pair was measured on 2.1.247 across 16 self-paired rounds, the same instructions in both languages, byte sizes matching within 1.4 percent. English came in at 604 tokens and Chinese at 678, a modal difference of 74 tokens or 1.12x. Two popular intuitions are both wrong by a wide margin: that CJK is punishingly expensive (a per-character reading suggests 2 to 3x) and that it is cheap because it uses fewer characters (a character-count reading suggests 0.36x, and the measurement is 2.7x above that). Per byte the rates are 0.388 and 0.441. The arms overlap round to round, so 1.12x is a modal difference rather than a resolved effect. See the measurement.