Claude Content Optimizer: Managing Context Window Budgets

Keep Claude Code's context window from filling and degrading by budgeting what enters it and compacting or clearing on purpose.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

Every Claude Code session runs inside one context window, and that window is the budget this skill manages. According to Claude Code's context window documentation, the window holds your instructions, the files Claude reads, its own responses, and content that never appears in your terminal. The Claude Code best practices add that it also carries every command output. Text that has scrolled off your screen is not gone; it is still in the window and still competing for attention on every turn.

The reason to budget it is output quality, not only cost. Anthropic's best-practices guidance builds most of its advice on a single constraint: the window fills quickly, and performance degrades as it fills, particularly during debugging or broad codebase exploration. A practitioner comparison of coding agents reports that performance starts to decline at roughly 50% fill, about 100,000 tokens, with developers reporting dramatic degradation at 75%, about 150,000 tokens. Treat those as field observations rather than benchmark results. They still match the symptoms heavy users describe: constraints set early in the session stop being honoured, and Claude re-reads files it has already seen.

This skill covers four things. First, knowing what consumes context so you can see where the budget went. Second, compacting deliberately: Anthropic defines compaction as summarizing a conversation that is nearing the window limit and restarting a new window with that summary, and Claude Code lets you steer the summary with a focus and choose the threshold at which it runs automatically. Third, recognizing the fill levels at which output gets worse. Fourth, avoiding the large file reads and unfiltered command output that burn budget without adding signal.

The output of practicing this skill is a session that stays sharp for the length of a real task: a lean starting context, a known point at which you compact or clear, and a habit of pulling in only the slice of a file or log that the next step needs. You can tell it is working when Claude still respects rules you stated at the start, and when automatic compaction rarely arrives as a surprise.

For background on why context is treated as a scarce resource and how budgeting fits alongside retrieval, memory and tools, see the Claude Code Context Engineering 6 Pillars Framework. This page stays on the mechanics of spending and reclaiming tokens inside a session.

How It Works

Think of the window as four streams drawing on one account. Persistent instructions such as CLAUDE.md load at the start and stay for the whole session. The conversation itself grows with every prompt and every reply. File reads land in full unless you ask for less. Command output, test logs and tool results arrive as raw text. The Claude Code best practices are explicit that the conversation, every file Claude reads and every command output all remain part of the context. The practical consequence is that one careless cat of a large log or one full test-suite dump can cost more than an hour of conversation.

You reclaim budget in two ways: summarizing or discarding. Compaction, as Anthropic describes it, replaces a long history with a summary and restarts the window from that summary. Claude Code does this automatically when it approaches the limit, and the best practices say automatic compaction preserves important code and decisions while freeing space. A summary is shorter than what it replaces, so something is always dropped. The only question is whether you or the default heuristics decide what. Clearing discards everything, which is the right move when the next task shares nothing with the last one.

The four controls and when each fits:

A focused compaction looks like /compact focus on the auth bug fix, the example given in Claude Code's context window documentation. The focus tells the summarizer which thread of work must survive intact, so exploratory dead ends and unrelated file contents are the parts that get squeezed out.

Deciding when to act comes down to fill level and task boundaries. The practitioner observations of decline near 50% fill and sharp degradation near 75% suggest acting well before the hard limit, not at it. Note that the autocompact example in the documentation is expressed as an absolute token count while those observations are expressed as fill percentages of a smaller window, so calibrate your threshold to the window size you actually run with. A reasonable rule: compact at natural milestones inside one task, clear at the boundary between tasks, and keep automatic compaction as the backstop.

The last lever is prevention. Anthropic's guidance recommends limiting broad investigations and delegating research to subagents, so exploration happens in a separate window and only the conclusion comes back into yours.

Step-by-Step Guide

Step 1: Inventory the starting budget

Before the first real prompt, look at what is already loaded: CLAUDE.md, any imported files, and skill or tool descriptions. Use whatever context view your setup provides to see how much of the window is spent before work begins. If persistent instructions already take a large share, trim them now, because they are paid for on every turn of the session. Write down the starting fill so you have a baseline to compare against later.

Pro tip: If you cannot explain why a paragraph of CLAUDE.md needs to be present for every task, move it into a file Claude reads only when relevant.

Step 2: Set your autocompact threshold

Choose the fill level at which automatic compaction should run instead of accepting the default trigger. The context window documentation shows /autocompact 500k as an example of setting that point. Pick a value comfortably below the level where you have seen output degrade on your own projects. This turns automatic compaction from a last-second emergency into a predictable event you can plan around.

Pro tip: For example, if your window is small, start with a threshold around half of it and adjust after a week of sessions.

Step 3: Scope every read and every command

Ask for the function, the line range or the grep match you need rather than the whole file. Pipe long command output through filters such as tail, grep or a failing-tests-only flag before it reaches the session. The best practices note that every file read and command output stays in context, so an unfiltered dump is a permanent cost until you compact or clear. When Claude proposes reading a large file, redirect it to the specific section.

Pro tip: Keep a short list of filtered versions of your common commands, such as the test runner showing failures only, and reference it in prompts.

Step 4: Delegate broad investigations

When a question requires scanning many files, such as finding every caller of an API, hand it to a subagent. Anthropic's guidance recommends limiting broad investigations and delegating research to subagents for exactly this reason. The subagent spends its own window on the search and returns a summary, so your main session receives the answer without the raw exploration. Ask the subagent for a concise result with file paths, not a narrative of everything it opened.

Step 5: Compact with a focus at milestones

When a sub-goal is done, such as the bug reproduced or the failing test identified, run a focused compaction before moving on. Name the thread that must survive, in the style of /compact focus on the auth bug fix from the context window docs. Then check the summary: the current plan, key decisions and relevant file paths should all be present. If something important is missing, restate it in your next prompt so it re-enters the fresh window.

Pro tip: Compact right after a success, not in the middle of a failing attempt, so the summary records the working state rather than the confusion.

Step 6: Clear between unrelated tasks

When the next piece of work shares no files or decisions with the last, run /clear, as the best practices recommend between unrelated tasks. Carrying the old task forward only adds tokens that compete with the new one. Before clearing, capture anything worth keeping, such as a new project gotcha, in CLAUDE.md or a notes file. Start the new task with a scoped prompt that names the files and the definition of done.

Step 7: Watch for degradation and reset early

Learn the symptoms: Claude ignores a constraint it followed an hour ago, re-reads a file it already summarized, or reintroduces a bug it fixed earlier. These are signs the window is past its useful fill, consistent with the practitioner reports of decline around half fill. When you see them, stop adding prompts and compact with a focus or clear and restart with a clean brief. Pushing on in a degraded session usually costs more tokens than the reset.

Pro tip: Keep a two-line task brief in a scratch file so restarting after a clear takes seconds.

Best Practices

• Budget from the start, not from the limit. The documentation notes the window fills quickly during debugging and exploration, so the time to plan compaction is before the session gets busy.
• Prefer targeted reads over whole files. Because every file read stays in context, asking for a function or a line range keeps the budget for reasoning instead of storage.
• Always give /compact a focus. A focus such as the one in the context window docs tells the summarizer what must survive, which is the difference between a useful summary and a generic one.
• Set an explicit autocompact threshold. Choosing the trigger with /autocompact, as the documentation shows, means compaction happens at a level you know is still healthy rather than at the edge of the window.
• Use subagents as disposable windows for exploration. Research done in a subagent, as Anthropic recommends, returns only its conclusion, so your main session never pays for the search.
• Treat task boundaries as reset points. Running /clear between unrelated tasks, per the best practices, is cheaper than letting old history quietly compete with new instructions.
• Persist lessons before you discard history. Anything you would want in the next session belongs in CLAUDE.md or a notes file, because neither clearing nor compaction guarantees it survives.

Common Mistakes

• Reading large files repeatedly or letting full command output into the session.: Each read and each output remains part of the conversation context. Filter output before it arrives and ask for specific sections of files.
• Waiting until the window is completely full and relying on automatic compaction.: Automatic compaction exists, but manual compaction lets you decide what is preserved. Compact with a focus at milestones and set a lower autocompact threshold so the backstop fires early.
• Reusing one congested conversation indefinitely across tasks.: A crowded window degrades performance as it fills. Compact with a focus if the task continues, or clear and start fresh if it does not.
• Running /compact with no focus and trusting the summary blindly.: An unfocused summary may drop the decision you care about most. Name the thread in the command and read the result before continuing.
• Treating published fill thresholds as universal constants.: The 50% and 75% degradation figures are practitioner observations, not controlled results. Use them as a starting point and calibrate against the symptoms you see on your own codebase.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: Claude Code Context Engineering: 6 Pillars Framework

Related Skills

• Writing Effective System Prompts for Claude AI
• Structuring Retrieval-Augmented Context for Claude
• Preventing Context Poisoning, Distraction, and Clashes
• Engineering Tool Output Context Flows for Claude Agents
• Layering Instruction Hierarchies in Claude Prompts
• Designing Multi-Turn Conversation Context Strategies

Sources

• Effective context engineering for AI agents - Anthropic
• Best Practices für Claude Code
• Best practices for Claude Code
• Google Antigravity vs Claude Code: Agent-First
• Explore the context window - Claude Code Docs

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.