{ "measurement": "What a CLAUDE.md actually costs per turn, split by billing tier", "claude_code_version": "2.1.233", "claude_code_version_recorded_at_runtime": "2.1.233 (Claude Code)", "what_this_adjudicates": "Circulating optimisation advice states it flatly: 'It injects into every request as system context. A 5,000-token CLAUDE.md is a 5,000-token tax per turn.' That is in no vendor doc and it is two claims wearing one coat: (a) the file is re-sent on every turn, which is about context, and (b) that costs you 5,000 tokens' worth every turn, which is about money. They come apart, because a re-sent prefix that is CACHED bills at a tenth of a fresh one.", "method": { "shape": "One session of 4 turns, resumed via --resume so it is genuinely one conversation. Two arms differing only by the presence of a CLAUDE.md of 18000 bytes of ordinary English prose.", "estimator": "MEDIAN across rounds per (arm, turn) cell. Declared once and used for every figure. The assembler refuses to build if any median is a value no round produced.", "population": "The per-turn cell. Turn-to-turn figures are differences between cells, never a pooled mean.", "billing_split": "input, cache_creation and cache_read are kept SEPARATE for every turn. Summing them into one number is precisely what makes the two claims above look like the same claim.", "controls": { "same_session": "The session_id returned by turn 1 is fed to --resume, asserted onto the command line, and every turn's returned id is published so a reader can check all turns were one conversation.", "arrival": "Every turn asks for a distinct marker and the reply must contain it, so a turn that silently did nothing is scored failed rather than as a cheap turn. Published per run as marker_arrived.", "fixture_both_ways": "The CLAUDE.md byte size is read back off disk per run and published, and the no_md arm asserts the file is ABSENT, so the treatment is proved on both sides.", "isolation": "--setting-sources project asserted onto the command line.", "cost_is_measured_not_modelled": "cost_usd comes from the CLI's own total_cost_usd per turn. The rate implied by dividing it by the token difference is reported, but it is derived FROM the measurement rather than assumed and then used." } }, "results": { "claude_md_tokens": 4967, "claude_md_bytes": 18000, "tokens_per_byte": 0.2759, "per_turn": { "1": { "context_no_md": 22287, "context_with_md": 27254, "context_difference": 4967, "cache_creation_no_md": 5747, "cache_creation_with_md": 10714, "cache_creation_difference": 4967, "cache_read_no_md": 16016, "cache_read_with_md": 16016, "cache_read_difference": 0, "cost_no_md": 0.06624, "cost_with_md": 0.1159, "cost_difference": 0.04966, "implied_rate_usd_per_mtok": 10.0, "rounds": 4 }, "2": { "context_no_md": 21772, "context_with_md": 26739, "context_difference": 4967, "cache_creation_no_md": 5759, "cache_creation_with_md": 10726, "cache_creation_difference": 4967, "cache_read_no_md": 16011, "cache_read_with_md": 16011, "cache_read_difference": 0, "cost_no_md": 0.06578, "cost_with_md": 0.11545, "cost_difference": 0.04967, "implied_rate_usd_per_mtok": 10.0, "rounds": 4 }, "3": { "context_no_md": 21793, "context_with_md": 26760, "context_difference": 4967, "cache_creation_no_md": 21, "cache_creation_with_md": 21, "cache_creation_difference": 0, "cache_read_no_md": 21770, "cache_read_with_md": 26737, "cache_read_difference": 4967, "cost_no_md": 0.01131, "cost_with_md": 0.01379, "cost_difference": 0.00248, "implied_rate_usd_per_mtok": 0.5, "rounds": 4 }, "4": { "context_no_md": 21813, "context_with_md": 26780, "context_difference": 4967, "cache_creation_no_md": 20, "cache_creation_with_md": 20, "cache_creation_difference": 0, "cache_read_no_md": 21791, "cache_read_with_md": 26758, "cache_read_difference": 4967, "cost_no_md": 0.01126, "cost_with_md": 0.01374, "cost_difference": 0.00248, "implied_rate_usd_per_mtok": 0.5, "rounds": 4 } }, "verdict": { "context": "TRUE. The file adds exactly 4,967 tokens to every single turn's context, identical on all 4 turns. It does not decay.", "money": "FALSE after the first two turns. The same 4,967 tokens cost $0.04966 and $0.04967 on turns [1, 2] and $0.00248 on turns [3, 4], about a 20x drop, because the file moves from being WRITTEN to cache to being READ from it. Each turn's own figure is given because they differ in the fifth decimal and a single number for both would be a value neither turn produced.", "why_two_turns_and_not_one": "NOT inferred here, CITED: cache-ttl.json measured that the FIRST resume always writes a new cache breakpoint over the grown conversation, identically at 5s, 60s and 480s gaps. That is why turn 2 pays the write rate again. This run reproduces it independently and in a place that owes nothing to the treatment: the no_md arm, with no CLAUDE.md at all, writes 5,759 tokens to cache on turn 2 and only 21 on turn 3. The two-turn shape is a property of the session, not of the file." }, "cross_version": { "previous_version": "2.1.232 (Claude Code)", "claude_md_tokens_then": 4969, "claude_md_tokens_now": 4967, "difference": -2, "reading": "The same fixture measured on the previous release, as a durability check. Same bytes, same prose, so a difference here is the tokeniser or the prompt assembly changing, not the file." } }, "known_limits": { "one_file_shape": "One CLAUDE.md of ordinary English prose. This site has measured the byte-to-token rate varying from 0.26 to 0.37 with content, so a file of tables or code will not cost the same per byte.", "four_turns": "Turns 1 to 4 only. Nothing here says what happens on turn 20, or after a compaction, or after an idle gap long enough to expire the cache.", "trivial_turns": "Every turn is a two-word reply. A turn that does real work adds its own tokens on top; what is isolated here is the CLAUDE.md's marginal contribution, not a whole session's cost.", "the_implied_rate_is_derived": "The per-Mtok figures are the measured cost difference divided by the measured token difference. They are not a quoted price list and are not used to compute anything else here.", "the_phantom_median_check_is_waived_for_cost_and_only_for_cost": "Token counts are discrete and this site refuses to publish a median no round produced. Cost is a continuous float, so with an even number of rounds its median is interpolated BY CONSTRUCTION and can never satisfy that check. The assembler therefore waives the check for cost_usd alone, which is a real weakening and is disclosed rather than hidden. Two things limit the damage: every cost cell's full set of rounds is published as cost_usd_all so a reader can compute their own estimator, and at the 5-decimal precision actually published the interpolated value falls inside the observed range in every cell. The headline separation does not lean on the estimator either way: the arms are DISJOINT on every turn, the cheapest with_md round costing more than the dearest no_md round.", "one_machine_one_model": "Opus on Claude Code 2.1.233, project scope only." }, "runs": [ { "arm": "no_md", "round": 0, "turn": 1, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "ALPHA", "marker_arrived": true, "session_id": "28c8af59-b933-470a-91dc-1eefa4d9d2ee", "resumed_from": null, "input": 524, "cache_creation": 5747, "cache_read": 16016, "context": 22287, "cost_usd": 0.06624 }, { "arm": "no_md", "round": 0, "turn": 2, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "BRAVO", "marker_arrived": true, "session_id": "28c8af59-b933-470a-91dc-1eefa4d9d2ee", "resumed_from": "28c8af59-b933-470a-91dc-1eefa4d9d2ee", "input": 2, "cache_creation": 5759, "cache_read": 16011, "context": 21772, "cost_usd": 0.0657805 }, { "arm": "no_md", "round": 0, "turn": 3, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "CHARLIE", "marker_arrived": true, "session_id": "28c8af59-b933-470a-91dc-1eefa4d9d2ee", "resumed_from": "28c8af59-b933-470a-91dc-1eefa4d9d2ee", "input": 2, "cache_creation": 21, "cache_read": 21770, "context": 21793, "cost_usd": 0.011305 }, { "arm": "no_md", "round": 0, "turn": 4, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "DELTA", "marker_arrived": true, "session_id": "28c8af59-b933-470a-91dc-1eefa4d9d2ee", "resumed_from": "28c8af59-b933-470a-91dc-1eefa4d9d2ee", "input": 2, "cache_creation": 20, "cache_read": 21791, "context": 21813, "cost_usd": 0.011255500000000002 }, { "arm": "with_md", "round": 0, "turn": 1, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "ALPHA", "marker_arrived": true, "session_id": "930cc555-fddd-4f9c-8ad2-b34416a8467e", "resumed_from": null, "input": 524, "cache_creation": 10714, "cache_read": 16016, "context": 27254, "cost_usd": 0.11589999999999999 }, { "arm": "with_md", "round": 0, "turn": 2, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "BRAVO", "marker_arrived": true, "session_id": "930cc555-fddd-4f9c-8ad2-b34416a8467e", "resumed_from": "930cc555-fddd-4f9c-8ad2-b34416a8467e", "input": 2, "cache_creation": 10726, "cache_read": 16011, "context": 26739, "cost_usd": 0.1154505 }, { "arm": "with_md", "round": 0, "turn": 3, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "CHARLIE", "marker_arrived": true, "session_id": "930cc555-fddd-4f9c-8ad2-b34416a8467e", "resumed_from": "930cc555-fddd-4f9c-8ad2-b34416a8467e", "input": 2, "cache_creation": 21, "cache_read": 26737, "context": 26760, "cost_usd": 0.0137885 }, { "arm": "with_md", "round": 0, "turn": 4, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "DELTA", "marker_arrived": true, "session_id": "930cc555-fddd-4f9c-8ad2-b34416a8467e", "resumed_from": "930cc555-fddd-4f9c-8ad2-b34416a8467e", "input": 2, "cache_creation": 20, "cache_read": 26758, "context": 26780, "cost_usd": 0.013739000000000001 }, { "arm": "no_md", "round": 1, "turn": 1, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "ALPHA", "marker_arrived": true, "session_id": "df5b21df-2cd2-4986-8c40-e509cc3c6853", "resumed_from": null, "input": 524, "cache_creation": 5747, "cache_read": 16016, "context": 22287, "cost_usd": 0.066235 }, { "arm": "no_md", "round": 1, "turn": 2, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "BRAVO", "marker_arrived": true, "session_id": "df5b21df-2cd2-4986-8c40-e509cc3c6853", "resumed_from": "df5b21df-2cd2-4986-8c40-e509cc3c6853", "input": 2, "cache_creation": 5759, "cache_read": 16011, "context": 21772, "cost_usd": 0.0657805 }, { "arm": "no_md", "round": 1, "turn": 3, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "CHARLIE", "marker_arrived": true, "session_id": "df5b21df-2cd2-4986-8c40-e509cc3c6853", "resumed_from": "df5b21df-2cd2-4986-8c40-e509cc3c6853", "input": 2, "cache_creation": 21, "cache_read": 21770, "context": 21793, "cost_usd": 0.011305 }, { "arm": "no_md", "round": 1, "turn": 4, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "DELTA", "marker_arrived": true, "session_id": "df5b21df-2cd2-4986-8c40-e509cc3c6853", "resumed_from": "df5b21df-2cd2-4986-8c40-e509cc3c6853", "input": 2, "cache_creation": 20, "cache_read": 21791, "context": 21813, "cost_usd": 0.011255500000000002 }, { "arm": "with_md", "round": 1, "turn": 1, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "ALPHA", "marker_arrived": true, "session_id": "0ab8c724-b780-429c-9d29-d37d9206fef5", "resumed_from": null, "input": 524, "cache_creation": 10714, "cache_read": 16016, "context": 27254, "cost_usd": 0.11589999999999999 }, { "arm": "with_md", "round": 1, "turn": 2, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "BRAVO", "marker_arrived": true, "session_id": "0ab8c724-b780-429c-9d29-d37d9206fef5", "resumed_from": "0ab8c724-b780-429c-9d29-d37d9206fef5", "input": 2, "cache_creation": 10726, "cache_read": 16011, "context": 26739, "cost_usd": 0.1154505 }, { "arm": "with_md", "round": 1, "turn": 3, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "CHARLIE", "marker_arrived": true, "session_id": "0ab8c724-b780-429c-9d29-d37d9206fef5", "resumed_from": "0ab8c724-b780-429c-9d29-d37d9206fef5", "input": 2, "cache_creation": 21, "cache_read": 26737, "context": 26760, "cost_usd": 0.0137885 }, { "arm": "with_md", "round": 1, "turn": 4, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "DELTA", "marker_arrived": true, "session_id": "0ab8c724-b780-429c-9d29-d37d9206fef5", "resumed_from": "0ab8c724-b780-429c-9d29-d37d9206fef5", "input": 2, "cache_creation": 20, "cache_read": 26758, "context": 26780, "cost_usd": 0.013739000000000001 }, { "arm": "no_md", "round": 2, "turn": 1, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "ALPHA", "marker_arrived": true, "session_id": "49b95135-b186-421c-95ef-7e48d7f0ac0f", "resumed_from": null, "input": 524, "cache_creation": 5747, "cache_read": 16016, "context": 22287, "cost_usd": 0.06623 }, { "arm": "no_md", "round": 2, "turn": 2, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "BRAVO", "marker_arrived": true, "session_id": "49b95135-b186-421c-95ef-7e48d7f0ac0f", "resumed_from": "49b95135-b186-421c-95ef-7e48d7f0ac0f", "input": 2, "cache_creation": 5759, "cache_read": 16011, "context": 21772, "cost_usd": 0.0657805 }, { "arm": "no_md", "round": 2, "turn": 3, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "CHARLIE", "marker_arrived": true, "session_id": "49b95135-b186-421c-95ef-7e48d7f0ac0f", "resumed_from": "49b95135-b186-421c-95ef-7e48d7f0ac0f", "input": 2, "cache_creation": 21, "cache_read": 21770, "context": 21793, "cost_usd": 0.011305 }, { "arm": "no_md", "round": 2, "turn": 4, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "DELTA", "marker_arrived": true, "session_id": "49b95135-b186-421c-95ef-7e48d7f0ac0f", "resumed_from": "49b95135-b186-421c-95ef-7e48d7f0ac0f", "input": 2, "cache_creation": 20, "cache_read": 21791, "context": 21813, "cost_usd": 0.011255500000000002 }, { "arm": "with_md", "round": 2, "turn": 1, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "ALPHA", "marker_arrived": true, "session_id": "86317d6d-5c91-43a3-b496-daa8948b7c3b", "resumed_from": null, "input": 524, "cache_creation": 10714, "cache_read": 16016, "context": 27254, "cost_usd": 0.11589999999999999 }, { "arm": "with_md", "round": 2, "turn": 2, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "BRAVO", "marker_arrived": true, "session_id": "86317d6d-5c91-43a3-b496-daa8948b7c3b", "resumed_from": "86317d6d-5c91-43a3-b496-daa8948b7c3b", "input": 2, "cache_creation": 10726, "cache_read": 16011, "context": 26739, "cost_usd": 0.1154505 }, { "arm": "with_md", "round": 2, "turn": 3, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "CHARLIE", "marker_arrived": true, "session_id": "86317d6d-5c91-43a3-b496-daa8948b7c3b", "resumed_from": "86317d6d-5c91-43a3-b496-daa8948b7c3b", "input": 2, "cache_creation": 21, "cache_read": 26737, "context": 26760, "cost_usd": 0.0137885 }, { "arm": "with_md", "round": 2, "turn": 4, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "DELTA", "marker_arrived": true, "session_id": "86317d6d-5c91-43a3-b496-daa8948b7c3b", "resumed_from": "86317d6d-5c91-43a3-b496-daa8948b7c3b", "input": 2, "cache_creation": 20, "cache_read": 26758, "context": 26780, "cost_usd": 0.013739000000000001 }, { "arm": "no_md", "round": 3, "turn": 1, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "ALPHA", "marker_arrived": true, "session_id": "69a10d90-553e-482a-8ba5-b2b916949ad5", "resumed_from": null, "input": 524, "cache_creation": 5747, "cache_read": 16016, "context": 22287, "cost_usd": 0.066245 }, { "arm": "no_md", "round": 3, "turn": 2, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "BRAVO", "marker_arrived": true, "session_id": "69a10d90-553e-482a-8ba5-b2b916949ad5", "resumed_from": "69a10d90-553e-482a-8ba5-b2b916949ad5", "input": 2, "cache_creation": 5759, "cache_read": 16011, "context": 21772, "cost_usd": 0.0657805 }, { "arm": "no_md", "round": 3, "turn": 3, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "CHARLIE", "marker_arrived": true, "session_id": "69a10d90-553e-482a-8ba5-b2b916949ad5", "resumed_from": "69a10d90-553e-482a-8ba5-b2b916949ad5", "input": 2, "cache_creation": 21, "cache_read": 21770, "context": 21793, "cost_usd": 0.011305 }, { "arm": "no_md", "round": 3, "turn": 4, "status": "ok", "claude_md_bytes_on_disk": 0, "marker_expected": "DELTA", "marker_arrived": true, "session_id": "69a10d90-553e-482a-8ba5-b2b916949ad5", "resumed_from": "69a10d90-553e-482a-8ba5-b2b916949ad5", "input": 2, "cache_creation": 20, "cache_read": 21791, "context": 21813, "cost_usd": 0.011255500000000002 }, { "arm": "with_md", "round": 3, "turn": 1, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "ALPHA", "marker_arrived": true, "session_id": "b90f1f6f-fe53-4748-a4d1-127acc3b96fb", "resumed_from": null, "input": 524, "cache_creation": 10714, "cache_read": 16016, "context": 27254, "cost_usd": 0.11591499999999999 }, { "arm": "with_md", "round": 3, "turn": 2, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "BRAVO", "marker_arrived": true, "session_id": "b90f1f6f-fe53-4748-a4d1-127acc3b96fb", "resumed_from": "b90f1f6f-fe53-4748-a4d1-127acc3b96fb", "input": 2, "cache_creation": 10726, "cache_read": 16011, "context": 26739, "cost_usd": 0.1154505 }, { "arm": "with_md", "round": 3, "turn": 3, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "CHARLIE", "marker_arrived": true, "session_id": "b90f1f6f-fe53-4748-a4d1-127acc3b96fb", "resumed_from": "b90f1f6f-fe53-4748-a4d1-127acc3b96fb", "input": 2, "cache_creation": 21, "cache_read": 26737, "context": 26760, "cost_usd": 0.0137885 }, { "arm": "with_md", "round": 3, "turn": 4, "status": "ok", "claude_md_bytes_on_disk": 18000, "marker_expected": "DELTA", "marker_arrived": true, "session_id": "b90f1f6f-fe53-4748-a4d1-127acc3b96fb", "resumed_from": "b90f1f6f-fe53-4748-a4d1-127acc3b96fb", "input": 2, "cache_creation": 20, "cache_read": 26758, "context": 26780, "cost_usd": 0.013739000000000001 } ] }