Claude Code
What the tool actually costs and how it actually behaves, measured against its own documentation.
tools built from these findings
The practical guide
Ranked by measured impact: what actually cuts context cost, and what does not.
Context cost calculator
Estimate what a session costs from your own skill, MCP and CLAUDE.md configuration.
Measure your own project
The shell script that produced these figures, published in full so any claim can be rerun.
what things cost in context 28
Your skill description is cut at 1,536 characters, and the cap is a setting you can raise
A rare marker planted at a known character offset inside a skill description, then asked for. Text ending at 1,530 characters is answered from context with no tool calls, four rounds of four; text ending at 1,536 is never answered from context, and the model shells out to read the file instead. That lands within six characters of the documented skillListingMaxDescChars default of 1,536. A 51-character increase in the skill name moves it not at all, and the tail past the cut is text you wrote that Claude never sees when deciding whether your skill is relevant. Corrected 2026-08-21: an earlier version of this post framed the cut as undocumented and cited a 1,024-character maximum.
- cut between 1,530 and 1,536 characters
- at 1,400 in context 4 of 4 rounds
- at 1,550 in context 0 of 4 rounds
- documented cap 1,536, skillListingMaxDescChars default
A trending 817-skill pack costs about 56,600 tokens before you type anything
An 817-skill cybersecurity pack from GitHub Trending costs about 56,600 tokens of startup context in an empty isolated project, 69.30 per skill, from 24 readings of which 21 sit inside a 48-token band. The synthetic skills curve behind this site's own calculator interpolates to 13.46 per skill at that count, 5.15x low, and its 1,000-skill cell still re-measures correctly. Description uniqueness and the pack's extra frontmatter were each tested here and refuted; deleting 338KB of frontmatter moved the reading by 8 tokens. The cause is not established: neither the synthetic nor the real fixture carries its descriptions whole, which rules the comparison out as a test of what the words cost.
- pack mukul975/Anthropic-Cybersecurity-Skills, commit 4c0b700
- skills 817, counted off disk on every arm run
- measured 56,622 tokens, 69.30 per skill
- published 30 rounds, 80 runs, five arms
"A 5,000-token CLAUDE.md is a 5,000-token tax per turn." Half of that is true.
An 18KB CLAUDE.md adds 4,967 tokens to every turn of a session on Claude Code 2.1.233, and it never decays. But it costs $0.04966 and $0.04967 on turns one and two and $0.00248 on turns three and four, because the file stops being written to cache and starts being read from it. The context claim is true and the cost claim is true for about two turns.
- claude code 2.1.233
- runs 32, no exclusions
- CLAUDE.md 18,000 bytes, 4,967 tokens
- added to every turn 4,967, all 4 of 4 turns
400 commands cost 9,989 tokens. 400 agents cost 20,404.
One widely shared write-up prices a plugin at about 100 words of metadata each and tells you to keep four to six. Measured on 2.1.231, a plugin has no single price: a skill or a slash command costs about 40 tokens and collapses in bulk, while a subagent definition costs 51 and never does.
- claude code 2.1.231
- re-verified on 2.1.232 reproduced, within one 198-token component
- runs 88, no exclusions
- a slash command 40.0 tokens, then 5.6
- re-verified on 2.1.238 8 rounds, marginal rates reproduced
The same forty skills cost 1,558 tokens, or 152
A skill is not a fixed price. On a clean project the marginal cost falls from 39.0 tokens to 3.9 between 200 and 400 skills; on a configured machine it is 3.8 straight away. That is where this site measured 1.5 tokens a skill from, and why that figure never reproduced in isolation.
- claude code 2.1.231
- runs 132, no exclusions
- clean project, below 200 skills 39.0 tokens each
- clean project, past 400 skills 3.9 tokens each
- re-verified on 2.1.233 unchanged, 39.05 per skill at 200
A 7.9MB node_modules cost 2 tokens, and .claudeignore does nothing
Measured on Claude Code 2.1.229. A lean project cost 22,401 tokens at startup in four runs out of four, identically. The same project carrying 7.9MB and 1,960 files of node_modules cost 22,403. Across 24 runs, including 12 that invited exploration, node_modules was read zero times. A .claudeignore excluding it did not stop a file inside it being read, 3 of 3, while the documented deny rule blocked it 3 of 3.
- claude code 2.1.229
- lean project, startup 22,401 tokens, 4 of 4 identical
- plus 7.9MB node_modules 22,403 tokens (+2)
- node_modules read 0 times in 24 runs
The 150-rule limit for CLAUDE.md measures something a CLAUDE.md is not
Measured on Claude Code 2.1.229 across 35 runs, no exclusions. A rule at the top of the file and a rule at the very bottom were both obeyed in 15 of 15 function definitions at 2, 10, 50, 150, 300 and 500 rules. The negative control scored 0 of 15 on both. This does not refute the benchmark behind the 150 figure, which measures a different thing. What 500 rules did cost was 23,427 tokens of context.
- claude code 2.1.229
- runs 35, no exclusions
- rule counts tested 2, 10, 50, 150, 300, 500, plus a control
- top rule 15 of 15 at every count
Fanning out was about 1.7x slower on work built to favour it
Measured on Claude Code 2.1.229 across 24 runs with no exclusions. Eight agents took 29.6s against 16.8s inline, a 12.8-second gap; four took 20.0s against 11.7s. Tokens ran 1.82x and 2.17x. Every arm is separated. The delegation control confirms the parent made zero file operations in all twelve fan-out runs, which took a field called parent_tool_use_id to establish.
- claude code 2.1.229
- runs 24, no exclusions
- eight agents 29.6s against 16.8s inline
- four agents 20.0s against 11.7s inline
Halving the output saved 6.8% of the bill
Measured on Claude Code 2.1.229 across 30 runs in three batches, no exclusions. Output is 1.45% of billed tokens and 10.2% of cost, seven times its token weight, because the input side is mostly cache reads at a tenth of the output rate. A terseness instruction halved the output and saved 6.8%. Every terse run cost less than every default run.
- claude code 2.1.229
- runs 30, no exclusions, three batches
- reply length 4,733 chars to 1,969
- output tokens 1,821 to 842 median, a 54% cut
Forcing the cache expiry everyone warns about made the session 7.6% cheaper
Measured on Claude Code 2.1.229 across 24 runs with no exclusions. After an eight-minute break the next turn cost $0.017 on the default cache and $0.118 with the five-minute TTL forced on, 6.8x. Summed over all three turns the same forced arm cost $0.370 against $0.400, and every forced run beat every default run. It wrote 50% more cache tokens and still cost less. A separate bracket found the default cache alive at 55 minutes and gone by 70.
- claude code 2.1.229
- runs 24, no exclusions (15 + a 9-run hour bracket)
- turn after an 8-minute break $0.017 default, $0.118 forced 5m
- whole 3-turn session $0.400 default, $0.370 forced 5m
The third step cost less than the first, in the session that was never cleared
Measured on Claude Code 2.1.228, ten rounds per arm, on three steps where each builds on the last. Keeping one session cost 274,436 tokens against 344,408 for clearing between every step, with the fresh arm dearer in 10 of 10 paired rounds. Both lose to asking once: the worst single-prompt run beat the best run of either multi-prompt arm on every measure. All 30 runs passed the hidden suite.
- claude code 2.1.228
- rounds 10 per arm, 30 runs on 2.1.228
- one prompt 103,828 tokens, $0.1697
- one session, three prompts 274,436 tokens, 2.64x
- re-verified 2.1.229, every claim held
Planning made the execution cheaper, and cost more than the job it was planning
Measured on Claude Code 2.1.228. Plan-then-execute and straight auto-accept were run four times each on the same bug fix with an objective pass/fail. Both passed 4 of 4. Planning genuinely made the doing cheaper, $0.1685 against $0.2062, but the plan call cost $0.2301 on its own, six times the saving it bought. The workflow cost 1.69x the tokens and 1.95x the dollars.
- claude code 2.1.228
- auto-accept, one call $0.2062 median
- execute call, plan in hand $0.1685, cheaper 4 of 4
- plan call alone $0.2301, dearer 4 of 4
Planning helped least on exactly the work its advice recommends it for
Measured on Claude Code 2.1.228 over seven paired rounds, with an open-ended prompt and a hidden rubric applied afterwards. Plan-then-execute cost 2.29x the tokens, 2.27x the dollars, 2.14x the turns and 2.17x the tool calls, with no overlap on any of them. Every run in both arms scored full marks on the rubric, which is a real limit on what the quality comparison can say, and the plan arm paid for a broken exit tool, which makes the ratios upper bounds.
- claude code 2.1.228
- paired rounds 7, bash control 22/22
- auto-accept $0.2910, 146,179 tokens
- plan then execute $0.6600, 334,425 tokens
The plan cost 1.47x the whole job, and made the job 29% cheaper
Measured on Claude Code 2.1.228, eight runs per arm, with --allowedTools Bash on every call in both arms and a full tool-call record behind every turn count. Plan-then-execute cost 2.01x the tokens and 2.18x the dollars of straight auto-accept, with no overlap. Split by call: the execute call is cheaper than doing it in one shot in 8 of 8, and the plan call alone is dearer than the entire one-shot run in 8 of 8.
- claude code 2.1.228
- runs 8 per arm, bash control 24/24
- auto-accept, whole job $0.1493, 114,268 tokens
- plan call alone $0.2192, dearer 8 of 8
The same fan-out costs 53% more, about a third of the time
Measured on Claude Code 2.1.228 across 26 runs. An eight-agent fan-out has two execution modes separated by num_turns: nine turns costs 207,102 tokens, one turn costs 317,786, for the same eight files. It happened in 3 of 10 runs, which means a single measured figure for per-agent cost is not one number.
- claude code 2.1.228
- cheap mode, 8 agents 207,102 tokens (turns=9)
- expensive mode, 8 agents 317,786 tokens (turns=1)
- difference 1.534x, +53.4%
Each parallel subagent costs 20,398 tokens, or 92,304 with your config loaded
Measured on Claude Code 2.1.227 across 44 runs, of which 4 sit behind the configured figure. Cost per parallel subagent is flat at about 20,400 tokens on a minimal config, so eight agents cost 3.2x one rather than 8x. On a machine carrying 37,808 tokens of user-level configuration, the per-agent cost rises to 92,304, which is about twice that configuration rather than most of it. The 75,466 figure this post originally used was the same quantity counted twice; see the correction. Re-measured on 2.1.231 the same slope is 20,690 and 103,397, about twice the configuration again.
- re-verified on 2.1.232 unchanged at matched turn count
- claude code 2.1.227
- per parallel subagent 20,398 tokens
- per subagent, configured machine 92,304 tokens (4 runs)
The env var sold as a 90% saving cost 8% more
Measured on Claude Code 2.1.227 across 28 runs. The flag is real and it engages in print mode, but on both a cold and a genuinely warm parent it increased cost rather than reducing it, because each child inherits the parent conversation instead of skipping the prefix. Every flag-on run used more context than every flag-off run; cache creation barely moved and 97% of the increase arrived as cache reads.
- claude code 2.1.227
- cold session cost, 4 agents +8.1% with the flag on
- warm session cost, 4 agents +15.6% with the flag on
- cold total context +38.2%
A 2MB screenshot costs the same as a 623-byte one: 3,135 tokens
Measured the context cost of reading images at eleven sizes, twice each. A 3,366x range in file size produced a 5-token difference. Above 2000px the cost stops growing entirely, and a retina screenshot costs 1.69x a normal one for exactly the same picture.
- claude code 2.1.224
- 1568x1568 image 3,135 tokens
- same image at 2MB 3,140 tokens
- client-side resize cap 2000 px
A skill costs 1.5 tokens, an MCP tool 15, and a subagent 1.72x the whole task
Skills, MCP servers, subagents and CLAUDE.md do overlapping jobs at wildly different prices: 1.5 tokens, 15 tokens, 1.72x the entire task, and 0.26 tokens per byte on every single round trip. The right choice is usually obvious once you can see the numbers.
- claude code 2.1.226
- one skill ~1.5 tokens
- one MCP tool, deferred ~15 tokens
- one MCP tool, loaded ~304 tokens
Trimming CLAUDE.md saves under 4%. Batching your tool calls saves 49%
The advice circulating about Claude Code token costs is mostly unmeasured. Here is each common tip with the measurement next to it: what actually saves tokens, what saves a rounding error, and the two claims the numbers contradict outright.
- claude code 2.1.226
- batching tool calls saves 49%
- trimming an 8KB CLAUDE.md saves 3.6%
- 200 MCP tools, default 3,054 not 60,854
The same 28KB costs 7,379 tokens in CLAUDE.md and 4 tokens in a skill
Measured on Claude Code 2.1.224: a CLAUDE.md costs about 0.26 tokens per byte plus 106 tokens of fixed overhead, and that cost lands on every single session. The same bytes parked in a skill body cost 4 tokens until invoked.
- claude code 2.1.224
- 28KB in CLAUDE.md +7,379 tokens
- 28KB in a skill body +4 tokens
- ratio 1,845x
- re-verified on 2.1.227 mechanism holds; ratio is fragile
- re-verified on 2.1.228 +8,137 vs +5; ratio now ~1,620x, third value in three versions
Delegating to a subagent costs 1.72x and saves 6.4%
Measured on Claude Code 2.1.224: delegation buys a smaller parent context at a large one-off cost. The saving is exactly the content you kept out of the parent, so the trade only works if the session continues long enough to bank it. Also: .usage does not count subagent tokens at all.
- claude code 2.1.224
- inline 126,825 tokens
- via subagent ~218,000 tokens
- cost multiplier 1.72x
Trying a new --effort level costs 40,054 tokens. Switching back is free.
Measured on Claude Code 2.1.224: changing --effort does not change your context size at all, but the first run at each new level writes about 40,054 tokens of cache at $0.41 against $0.029 warm. Once a level is warm, alternating between levels is free.
- claude code 2.1.224
- first run at a new level 40,054 tokens created
- cost cold vs warm 13.9x
- switching back 0 tokens
Adding one 5-token skill costs 47,544 tokens
Measured on Claude Code 2.1.224: a warm session reads 66,078 cached tokens and reports $0.033. Change a single character of CLAUDE.md, or add one small skill, and the next session recreates 47,544 tokens of cache and reports $0.485. The file size barely matters; the invalidation does.
- claude code 2.1.224
- warm session 0 created, 66,078 read
- after any change 47,544 created
- cost multiplier 14.6x
Reading a 6-byte file costs 58,851 tokens
Measured on Claude Code 2.1.224: a tool call costs approximately your whole current context, regardless of what it returns. File content is only about 0.35 tokens per byte, so on a 40KB read the overhead is four times the file itself. Batching tool calls halves the total.
- claude code 2.1.224
- one tool round trip +58,851 tokens
- 3 reads batched 121,732 tokens
- 3 reads sequential 240,073 tokens
Resuming a session costs 43,350 tokens once, then 293 a turn
Measured on Claude Code 2.1.224: continuing a conversation adds exactly 293 tokens of cache write per trivial turn, with everything else served from cache. Across six turns the context grew 1,465 tokens while reported cost rose 2%.
- claude code 2.1.224
- first resume 43,350 tokens created
- each turn after 293 tokens created
- cost over 6 turns +2%
Turning off MCP tool search costs you 17,214 tokens before you connect anything
Measured context cost of MCP tools with tool search on and off, across 5, 50 and 200 tools. Deferring saves about 95%, an MCP tool costs roughly 200 times what a skill costs, and disabling tool search adds 17,214 tokens to an empty session.
- claude code 2.1.223
- 200 tools deferred +3,054 tokens
- 200 tools loaded +60,854 tokens
- tool search off, no servers +17,214 tokens
- re-verified on 2.1.224 +17,795 tokens
- re-verified on 2.1.233 +14,644 tokens, down 17% from 2.1.232
What 1,000 skills actually cost you: 1,474 tokens
Measured prompt tokens across skill counts from 1 to 1,000, with body sizes from 200 bytes to 28KB and descriptions from 90 to 1,500 characters. Every configuration paired against a baseline measured in the same batch, because the baseline drifts.
- claude code 2.1.223
- 1000 skills cost 1,474 tokens
- on disk 3.9 MB
- 28KB body cost +5 tokens
- re-verified on 2.1.224 1,461 tokens
how it actually behaves 9
A deny rule on .env leaked nothing in 20 runs, and 14 of 24 got through another way
Measured on Claude Code 2.1.229 across 88 runs with a fabricated credential as the canary. With permissions.deny Read(./.env) in place, the Read tool, cat, head, sed and grep leaked 0 times in 20. A python one-liner, a node one-liner and dd leaked 14 times in 24. Every result matches the documented boundary; what the documentation does not convey is that the uncovered side has no enforcement, only judgement.
- claude code 2.1.229
- runs 88, canary-scored
- rule tested deny: Read(./.env)
- Read tool, cat, head, sed, grep 0 of 20 leaked, 18 blocked at the layer
Compaction kept all 64 planted values, across 24 compactions
Measured on Claude Code 2.1.228. Eight unguessable values were planted at spaced turns, the session was driven past the compaction threshold, and every value was asked back with files off-limits. 64 of 64 survived across 24 compactions and two bulk types. This tests recall of discrete stated values, which is not the same thing as preserving nuance, and the post says so.
- claude code 2.1.228
- values recalled 64 of 64
- compactions survived 24
- dense arm 32 of 32, 4 compactions per run
Claude Code's auto-compaction fails with `too_few_groups` when one turn fills your context
Measured when auto-compaction actually fires and whether it works. It reports a status event carrying compact_result and an undocumented compact_error. Filling the context in one turn produces failed / too_few_groups, reproducibly, which is precisely the case people hit.
- claude code 2.1.226
- single turn, 122,575 tokens failed / too_few_groups
- multi-turn, 115,471 tokens success
- --autocompact range auto or 100k–1M only
A 28KB CLAUDE.md costs 7,379 tokens and no measurable time
Measured on Claude Code 2.1.224: adding a 28KB CLAUDE.md produced a median time-to-first-token difference of 178ms, against run-to-run variance ranging from 1,527ms to 8,337ms on identical configurations. A sign test over 20 paired samples gives p = 0.263.
- claude code 2.1.224
- paired samples 20
- 28KB slower in 13 of 20
- sign test p 0.263
In Claude Code permissions, deny always wins
Eight headless runs across four settings configurations show a deny rule blocks a tool call regardless of which scope it sits in, even when a higher-precedence file explicitly allows the same pattern, and even inside the same file.
- claude code 2.1.223
- headless runs 8
- configurations 4
- control passed
Three ways to write a dead deny rule, one of them silent
Eighteen headless runs across five rule forms. A misspelled tool name warns, a raw-string matcher warns, and a misplaced colon fails completely silently while looking correct.
- claude code 2.1.223
- headless runs 18
- rule forms tested 5
- dead rules found 4
Nothing in a project can unset an inherited Claude Code env var
Measured how Claude Code combines the env setting across user, project, local and --settings. It deep-merges across all four, an inherited key cannot be removed from a higher-precedence scope, non-string values are silently coerced by JavaScript string conversion, and OTEL_ variables never reach subprocesses at all.
- claude code 2.1.224 (8a2a469b68f9)
- scopes env merges across 4 of 4
- ways to unset that work none cleanly
- null becomes the string "null"
Three Claude Code hook fields the docs name wrong
Wiring 15 hook events to a capture script and running two headless sessions turned up three field names that did not match the documentation on 2026-08-07, plus several useful fields undocumented at the time, including per-tool duration_ms. Re-checked on 2026-08-21: every one of those discrepancies has since been fixed in the hooks reference, so this now stands as a record rather than as current guidance.
- claude code 2.1.223
- hook events wired 15
- events captured 22
- sessions run 2
Subagents load CLAUDE.md invisibly
A general-purpose subagent provably reads your CLAUDE.md, and the hook meant to observe instruction loading never fires for it. If you use InstructionsLoaded to audit what reaches your agents, subagents are a blind spot.
- claude code 2.1.223
- headless sessions 5
- subagents spawned 5
- InstructionsLoaded events 8
keeping the numbers honest 1
Every measurement re-run on Claude Code 2.1.224: two were identical to the token
Claude Code 2.1.223 became 2.1.224. Re-measuring every figure this site has published shows the deltas are remarkably stable across the version bump, while the absolute baselines drift, which is precisely why paired baselines matter.
- claude code 2.1.224
- figures re-verified 11
- unchanged 9
- moved 2
- re-verified on 2.1.226 all figures hold
- re-verified on 2.1.227 batching 2.0x, mechanisms hold
- re-verified on 2.1.228 batching 2.0x, mechanisms hold, ratio moved again
- re-verified on 2.1.231 floor +64 tokens, tool-search delta held
running the site 1
Deploying a static site to Hostinger shared hosting
Both candidate folders carried a DO_NOT_UPLOAD_HERE marker and the domain resolved to an IP that was not the SSH host. Here is how to find the real document root in one command instead of guessing.
- host shared, no root
- node on PATH none
- node available v24.6.0
- time to find docroot one probe
Every figure is collected on the measurements page, and the method behind them is written up here.