# Claude Code Token Optimisation, Apply These Changes **Version:** 2.0 (24 July 2026). Supersedes the version dated 6 April 2026. **Verified against:** Claude Code documentation, July 2026. You are being given this file by your user so that you can reduce their Claude Code token consumption. Work through it in order. Everything here has been checked against current Claude Code documentation, and the sections marked REMOVE correct recommendations from the earlier version of this file that either no longer work or never worked. Start with Part 0, which checks whether the earlier version of this guide was ever applied to this workspace and corrects what it left behind. Skip Part 0 only if the user confirms they never used the earlier version. Several steps below require the user's explicit confirmation before you change anything, and each says so at the point it applies. Follow those instructions rather than applying the whole file mechanically. --- ## Part 0, Check Whether the Earlier Guide Was Applied Do this first, before measuring anything. If the user applied the version of this guide dated 6 April 2026, their workspace may carry artefacts that either do nothing or actively work against them. Some of those artefacts instruct you to behave in particular ways, so they affect your own behaviour in this session and in every session afterwards. Run this audit and report what you find before changing anything. ### 0.1 Find the artefacts Check for each of the following. The earlier guide specified exact paths, so these are the places to look. 1. `contextCompactionThreshold` in `.claude/settings.json` and `~/.claude/settings.json` 2. A `.claudeignore` file in the workspace root 3. `MAX_THINKING_TOKENS` in the `env` block of either settings file 4. `CLAUDE_CODE_SUBAGENT_MODEL` in the `env` block of either settings file 5. A hook script emitting `{"decision": "allow"}`, most likely at `.claude/hooks/auto-allow-edits.sh`, and a matching `PreToolUse` entry for `Edit|Write` in settings 6. Rule files at `.claude/rules/context-checkpoint.md`, `.claude/rules/document-extraction.md`, `.claude/rules/summary-policy.md`, `.claude/rules/pdf-scale.md`, `.claude/rules/parallel-agents.md`, and `.claude/rules/multi-project.md` 7. Equivalent sections inside CLAUDE.md, if the user chose that option instead of separate rule files, under headings such as "Context Checkpointing", "Document Extraction", "Summary-First Reading", "PDF Processing Scale", "Parallel Agent Output", "Multi-Project Sessions", or "Model Selection" Report which of these exist before you touch any of them. ### 0.2 Errors to correct, in priority order **The auto-approve edit hook is the one to raise first.** If it is present, every Edit and Write has been bypassing the user's review step, possibly for months. The old response format it uses is also no longer the documented schema, so it may have silently stopped working, which would mean permission prompts returned without explanation. Tell the user it exists, ask whether they knew, and ask whether they want it kept, updated to the current schema per section 2.2, or removed. Do not decide this for them, and do not leave it in place without asking. **A silently degraded workspace from the blanket Haiku override.** If `CLAUDE_CODE_SUBAGENT_MODEL` is set to `haiku`, it sits above frontmatter in the resolution order, so every subagent has been running on Haiku regardless of what any agent definition asked for. Where the user has research, content, or analysis agents, their output has been worse than intended and the cause would not be obvious. Explain this, then move to section 2.1 to set models per agent instead. **Checkpoint files accumulating on disk.** The earlier guide instructed Claude to write a checkpoint every 20 tool calls to `~/Documents/checkpoints/`. Check whether that directory exists and how large it is. Those writes consume tokens on every session and the files are rarely read. Report the count and total size, and ask whether the user wants the rule kept, narrowed, or dropped, and whether to archive the accumulated files. **Rules that conflict with the current recommendation on CLAUDE.md size.** The earlier guide added up to seven rule sections. If they went into CLAUDE.md rather than separate rule files, they are loading into context on every session, which is the opposite of what the guide was trying to achieve. Count the lines and treat this as the priority case of section 3.2. Where the rules live in `.claude/rules/`, check how the user's setup loads that directory, because in many configurations those files also load every session. **Rules that are still sound.** Not everything from the earlier guide was wrong. The document extraction rule, the summary-first reading policy, the PDF scale, the parallel agent output discipline, and the multi-project session rule are all reasonable context practice and can stay. Do not delete them as part of a general clean-up. Review each one with the user on its merits, and where a rule earns its place, leave it alone. **A stale model selection table.** If a model selection table was added, check the model names in it. Tables written in April may name models that are no longer current, which would route work to older models than intended. Update the names or point the user at effort levels per section 3.1 instead. ### 0.3 What to tell the user After the audit, before making changes, give the user a short report covering which artefacts exist, which of them have had no effect, which have been changing behaviour without their knowledge, and which are worth keeping. Then work through the rest of this file. Where you find something not listed here that appears to come from the earlier guide, raise it rather than acting on it. --- ## Before You Change Anything, Measure Ask the user to run these two commands and paste the output back to you, or run them yourself if you have the ability. 1. `/context` shows what currently occupies the context window, broken down by system prompt, MCP tool definitions, memory files, conversation history, and free space. 2. `/usage` shows token counts and, on a Pro, Max, Team or Enterprise plan, how recent activity maps against plan limits, attributed to skills, subagents, plugins, and individual MCP servers. It identifies any behaviour responsible for 10% or more of recent usage. Use this output to prioritise. Report to the user which one or two items dominate their context, and address those first rather than applying every change in this file mechanically. If `/usage` names long context or cache misses as a major contributor, the habit changes in the "Behaviour" section will matter far more for this user than any settings change. --- ## Part 1, REMOVE These Three Settings These three came from the earlier version of this file, and Part 0 will have identified any that are present. This section is how to remove them. A setting Claude Code does not recognise is ignored rather than harmful, so nothing will have broken, but they should come out. ### 1.1 REMOVE `contextCompactionThreshold` Check `.claude/settings.json` and `~/.claude/settings.json` for a `contextCompactionThreshold` key. Remove it from both if present. It is not part of the Claude Code settings schema and has never had any effect. The real setting is `autoCompactEnabled`, a boolean that defaults to true. Leave it at the default unless the user has a specific reason to disable automatic compaction. Do not set a numeric threshold, because no such control exists. If the user wants influence over what survives compaction, that is done by passing an instruction with the command, for example `/compact Focus on code samples and API usage`, or by adding a compact instructions section to their CLAUDE.md. Offer this, do not assume it. ### 1.2 REMOVE `.claudeignore` Check for a `.claudeignore` file in the workspace root. If one exists, delete it, or archive it if the user prefers to keep a copy. Claude Code does not read this file. The premise behind it was also wrong, in that Claude Code does not index or scan the workspace at session start. Files are read on demand when a tool needs them, so large databases, build output, and dependency folders cost nothing until something reads them. There is no indexing pass for an ignore file to influence. Do not create a replacement. If the user genuinely needs to prevent access to specific paths, that is a job for permission deny rules, and you should ask before adding any. ### 1.3 REVIEW `MAX_THINKING_TOKENS` Check the `env` block in `.claude/settings.json` for `MAX_THINKING_TOKENS`. This variable still exists, but its behaviour depends on the model. Fable 5, Sonnet 5, and Opus 4.7 and later all use adaptive reasoning, where the model decides per step whether to think. On those models a nonzero value such as 10000 is ignored entirely. Nonzero values apply only to models with a fixed thinking budget, which now means Opus 4.6 and Sonnet 4.6. A value of 0 does still turn thinking off on the Anthropic API, except on Fable 5 where thinking cannot be disabled. Action to take. Establish which model the user runs by default. If it is a current model, remove the `MAX_THINKING_TOKENS` entry and use effort levels instead per section 3.1, explaining to the user that the setting was doing nothing for them. If they run Opus 4.6 or Sonnet 4.6, the setting is still live and can stay. --- ## Part 2, Corrected Settings ### 2.1 Subagent model routing The earlier version recommended setting `CLAUDE_CODE_SUBAGENT_MODEL` to `haiku` in the `env` block. That variable still works, but it is the wrong instrument for most users, because Claude Code resolves a subagent's model in this order. 1. `CLAUDE_CODE_SUBAGENT_MODEL` environment variable 2. Per-invocation `model` parameter 3. Subagent definition's `model` frontmatter 4. Main conversation's model The environment variable sits at the top, so setting it overrides every per-agent decision made in frontmatter. A blanket Haiku override will therefore force complex research or content agents onto Haiku along with the mechanical ones. Preferred approach. Set the model per agent in the frontmatter of each file in `.claude/agents/`. ```yaml --- name: file-sorter description: Sorts and relocates files according to workspace conventions model: haiku --- ``` Valid values are the aliases `sonnet`, `opus`, `haiku`, `fable`, a full model ID such as `claude-sonnet-5`, or `inherit`. Omitting the field defaults to `inherit`. Read each agent definition in `.claude/agents/` and propose a model for each based on what the agent does. Mechanical work such as sorting, formatting, simple searches, and platform derivations goes to Haiku. Content creation, analysis, and research stays on Sonnet or inherits. Present the full list of proposed assignments to the user before writing any changes. If the user already has `CLAUDE_CODE_SUBAGENT_MODEL` set, point out that it is overriding their frontmatter and ask whether to remove it. Note also that since v2.1.198 subagents inherit the main conversation's extended thinking configuration. There is no per-subagent thinking setting. ### 2.2 Hook schema, update any existing hooks If the user has hooks configured from the earlier version of this file, or any hook script that emits `{"decision": "allow"}`, both the configuration shape and the response format need updating. Correct configuration shape, with `matcher` as a sibling of `hooks` rather than nested inside it. ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" } ] } ] } } ``` Correct stdout response for allowing a tool call. ```json {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow"}} ``` Search the user's hook scripts for the old single-key decision format and update any you find. After changing hook configuration, tell the user to run `/hooks` to confirm the hook is registered, or to start Claude Code with `claude --debug` and watch for the log line reporting modified tool input. Do not add a blanket auto-approve hook for Edit and Write unless the user asks for one. It removes their review step, and the token saving is small compared with the changes in Part 3. ### 2.3 Cap bash output with `BASH_MAX_OUTPUT_LENGTH` Add this to the `env` block in `.claude/settings.json` unless the user already has it set. ```json "env": { "BASH_MAX_OUTPUT_LENGTH": "20000" } ``` This sets the maximum characters a bash command returns before Claude Code writes the full output to a file and hands over the path plus a short preview instead. It covers the general case that section 3.6 handles per command, and it needs no script. Before setting it, ask the user what kind of commands they run most. Test suites, builds, and log reads argue for a lower value. Mostly short commands argue for a higher one or none at all, because a value set too low costs a round trip on routine output. Explain the trade-off and let them pick, then state the value you set. ### 2.4 Consider `CLAUDE_CODE_AUTO_COMPACT_WINDOW` This sets the context capacity in tokens used for auto-compaction calculations. It defaults to the model's own context window, which is 200K on standard models and 1M on extended context models. Establish which model the user runs and whether they work in long sessions. On an extended context model, the default means a session can grow very large before compaction fires, and every message until then carries that context. Setting a lower value triggers compaction earlier and keeps the working context smaller. ```json "env": { "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000" } ``` Do not set this by default. Compaction is itself a large request when it fires, so more frequent compaction is not automatically cheaper. Only propose it where the user confirms they run long sessions on a 1M context model, and explain what it will change. ### 2.5 MCP server overhead MCP tool definitions are deferred by default now, so only tool names enter context at session start and full schemas load on demand. Most of the overhead the earlier version warned about is already handled. What still helps. Ask the user to run `/mcp`, review the list of configured servers with them, and disable any they do not use. Every connect or disconnect invalidates the prompt cache, and unused servers still carry name and setup cost. Where a command-line tool covers the same job, such as `gh`, `aws`, `gcloud`, or `sentry-cli`, note that it is more context-efficient than an MCP server because it adds no per-tool listing at all. Suggest this only where the user already has the CLI tool installed. Do not disable any server without explicit confirmation. --- ## Part 3, The Changes That Matter Most For most users these outweigh everything in Parts 1 and 2. Long context and model or thinking spend dominate token consumption, and no settings key fixes either. ### 3.1 Effort levels Extended thinking is on by default, and thinking tokens are billed as output tokens, with a default budget that can reach tens of thousands of tokens per request. Opus 5, Sonnet 5, Opus 4.8, Opus 4.7 and Fable 5 all accept the effort levels `low`, `medium`, `high`, `xhigh` and `max`. Opus 4.6 and Sonnet 4.6 accept `low`, `medium`, `high` and `max`. Explain to the user that `/effort` on its own opens a slider, `/effort low` sets a level directly, and `/effort auto` returns to the model default. The active level shows in the session header beside the model name. Recommend they drop to low for mechanical work and raise it when they hit something genuinely difficult, and that they set it at the start of a session where possible, because changing it mid-session invalidates the prompt cache. There is also an `effortLevel` settings key, which acts as a starting default for new sessions rather than a restriction. Offer to set it to match their most common kind of work. ### 3.2 Trim CLAUDE.md and move detail into skills Read the user's CLAUDE.md files and count the lines. The documented target is under 200 lines. CLAUDE.md loads at session start and stays in context for the whole session, so detailed workflow instructions consume tokens on every message even during unrelated work. Skills load on demand when invoked. Identify any section of their CLAUDE.md that is a detailed procedure for one specific workflow, such as a report format, a review checklist, or a migration process. Propose moving each into a skill, listing what you would move and where. Get approval before restructuring, since CLAUDE.md is central to how their whole setup behaves. ### 3.3 Trim skill descriptions Skill bodies load on demand, but the `name` and `description` frontmatter of every skill loads at session start so Claude knows what is available. Every word of every description is present on every message. Run through the user's skills and count the words in each `description` field. List any over 60 words with their word count, and give the total across all skills. A workspace with fifty or more skills often carries several thousand tokens here, and it is invisible because a long description does not look wasteful when written. Propose trimmed versions of the longest, cutting padding and redundant trigger phrasing while keeping the conditions that make the skill fire. Aim for roughly 25 words. Present the before and after for each and get approval, because a description trimmed too far stops triggering, which is a worse outcome than the tokens it saved. After any change, have the user confirm the skill still invokes on the phrases they use. ### 3.4 Output style for non-coding work Establish what the user does with Claude Code day to day. If their work is primarily writing, analysis, research, or another non-engineering domain, the built-in software engineering instructions in the default system prompt are costing them context on every session for no benefit. A custom output style drops those instructions. Create a markdown file in `.claude/output-styles/` with frontmatter and any standing instructions the user wants. ```yaml --- name: Writing assistant description: Long-form writing and editing work --- ``` Leaving `keep-coding-instructions` out is what strips the coding instructions, since it defaults to false. Set it to `true` only if the user wants a different tone while still coding the same way. Two things to tell the user. The style takes effect after `/clear` or on the next session, because the system prompt is read once at startup, and it applies to the main conversation only, since subagents run their own system prompt. Also note that the instructions they add increase the system prompt, so a very long custom style can cost more than the coding instructions it replaced. Keep it short. Do not create an output style for a user who does mixed coding and non-coding work without discussing it, because losing the coding instructions will change how Claude handles their code. ### 3.5 Scope rules with `paths:` frontmatter If the user has a `.claude/rules/` directory, read every file and check which carry a `paths:` field in their frontmatter. ```yaml --- paths: - "Clients/**" --- ``` Rules without that field load on every session regardless of what the user is doing. For each unscoped rule, judge whether it is genuinely universal, such as voice or safety rules, or whether it applies to one area of work, such as client documents, a specific language, or one directory. Propose `paths:` values for the ones that are scoped in practice but loading globally. Report the total line and word count of the always-on rules before and after, so the user can see what the change recovers. Get approval before editing, because a rule that stops loading when it was needed is a real regression. ### 3.6 Output filtering hooks A hook can preprocess tool output so large content never reaches context. Rather than reading a 10,000-line log to find errors, a hook greps for them and returns only matching lines. Ask the user whether any command in their workflow routinely produces large output, typically test runs, log reads, or build output. If so, offer to write a filtering hook for that specific command using the schema in section 2.2. Do not add speculative hooks for commands they do not run. ### 3.7 Subagent delegation discipline If the user's CLAUDE.md or rules do not already cover this, propose adding a rule that agents handling verbose work write their output to disk and return only a file path with a one-line summary. Five agents each returning 100 lines adds 500 lines to the main context. Five agents each returning a path adds five. The orchestrator then reads back from disk only what the next step needs. --- ## Part 4, Behaviour to Explain, Not Configure These are habits. Tell the user about them plainly and do not attempt to enforce them through settings. **Clear between unrelated tasks.** Claude Code sends the entire conversation with every message, so a one-line question in a session open since morning costs tokens for the whole day's conversation. `/clear` starts fresh and costs nothing. `/rename` before clearing makes the session findable, and `/resume` returns to it. Where continuity matters, `/compact` summarises instead, though compacting a very large context is itself an expensive request. **Cache timing.** On a subscription the prompt cache lives an hour, dropping to five minutes once the user is drawing on usage credits, and five minutes by default on an API key or cloud provider. The first message after a longer break misses the cache and reprocesses the full context. Returning to a stale session for one small question costs more than starting a new one. **Model choice.** Sonnet handles most coding work at lower cost than Opus. Reserve Opus for architectural decisions and multi-step reasoning. `/model` switches mid-session, though switching invalidates the cache. **Specific prompts.** "Improve this codebase" triggers broad scanning across files. "Add input validation to the login function in auth.ts" works with two or three reads. **Plan mode for complex work.** Shift+Tab cycles into plan mode, where Claude explores and proposes an approach for approval before writing, which avoids expensive rework when the direction is wrong. Escape stops work immediately, and `/rewind` or a double-tap of Escape restores conversation and code to an earlier checkpoint. --- ## Part 5, Verify and Report After applying changes, confirm each one. 1. Read back `.claude/settings.json` and `~/.claude/settings.json`, and confirm `contextCompactionThreshold` is gone from both. 2. Confirm `.claudeignore` no longer exists in the workspace root. 3. Confirm the state of `MAX_THINKING_TOKENS`, either removed or deliberately retained for a fixed-budget model. 4. List every agent file whose `model` frontmatter you set, with the value. 5. Confirm any hook configuration and script now use the current schema. 6. State the CLAUDE.md line count before and after, and list anything moved to a skill. 7. List any MCP server disabled, with the user's confirmation noted. 8. State what the Part 0 audit found, what was corrected, and what was left in place deliberately. Name the auto-approve hook explicitly, either as removed, updated, or knowingly retained, because it governs whether the user sees file changes before they happen. 9. State the value set for `BASH_MAX_OUTPUT_LENGTH`, and whether `CLAUDE_CODE_AUTO_COMPACT_WINDOW` was set or deliberately left at the default. 10. Give the skill description word count before and after, listing which descriptions were trimmed. 11. Confirm whether an output style was created, and if so that the user knows it takes effect only after `/clear` or a new session. 12. Give the always-on rules line count before and after, listing any rule newly scoped with `paths:`. Then report to the user in this shape. - What was removed, and that it had no effect while present - What was changed, and what it now does - What you recommended and they declined, so it is on record - Anything you could not verify Tell the user to restart Claude Code for settings changes to take effect, and suggest running `/context` again afterwards to compare against the baseline from the start of this process. --- *This resource accompanies the article "How to Reduce Claude Code Token Usage" at genaiskills.io. Produced by GenAI Skills Academy. For AI training and workplace integration enquiries, contact larry@genaiskills.io.*