Claude Code Session Hygiene: How to Get Better Agent Output With Less Token Waste

Anthropic published “Maximizing the value of your Claude Code sessions” on August 14, 2026, and the timing matters. Coding agents are no longer short prompt-response helpers. Founders, operators, agencies, and developers are now leaving agents inside repositories for hours, asking them to inspect context, fix bugs, write tests, refactor modules, update docs, and coordinate across tools. In that world, the quality of the session becomes the quality of the work.

The practical takeaway is simple: session hygiene is now an engineering discipline. Anthropic’s guidance focuses on concrete habits inside Claude Code: use /clear between unrelated tasks, set /model and /effort before starting, @-mention files instead of casually naming them, inspect /context, keep CLAUDE.md lean, disable unneeded MCP servers, /rename before /clear, use /compact carefully, and use /autocompact 200k on 1M-context models when needed. These are not cosmetic commands. They reduce context pollution, preserve prompt cache behavior, and help the agent reason over the right files instead of dragging stale instructions through the session.

This post turns Anthropic’s guidance into workflows you can copy. You’ll see how disciplined session management improves solo bug fixing, agency multi-client worktrees, founder product iteration, repo onboarding, release QA, and documentation maintenance. Cost is the proof layer: fewer wasted tokens means cheaper runs, but the bigger win is better agent output with fewer dead-end loops.

---

What changed: Claude Code sessions are becoming persistent workspaces

The old coding-assistant pattern was transactional: paste an error, get an answer, copy a patch. Claude Code’s newer usage pattern is different. The agent lives inside a repository, reads files, uses tools, references prior turns, and accumulates context. That unlocks bigger work, but it also creates a new failure mode: context drift.

Context drift happens when the agent carries irrelevant or conflicting information from previous work. A bug-fix session still contains notes from a refactor. A client A worktree still includes assumptions from client B. An old file summary competes with the actual current file. A large CLAUDE.md injects too many global rules into every task. Unneeded MCP servers add tool descriptions and retrieval surfaces that the model must consider.

Anthropic’s August 14 guidance is timely because models such as Claude Opus 5, Claude Sonnet 5, GPT-5.2, and Gemini 3 Pro now support large-context, agentic development patterns. With 1M-token context windows available across top-tier models, developers can keep much more state in a session. But more context is only useful when it is relevant.

The market cares because agentic coding is moving from experiments to operations. A founder may use Claude Code to ship two product changes per day. An agency may run separate client worktrees with separate agents. A developer may keep one session alive through investigation, implementation, tests, and PR notes. In each case, the new bottleneck is not whether the model can write code. It is whether the agent has the right working memory.

---

The session hygiene tactics Anthropic highlighted

Anthropic’s recommendations are highly practical. Here is how to apply each one.

Use /clear between unrelated tasks

Use /clear when switching from one unrelated task to another: bug fix to feature work, frontend to backend migration, client A to client B, or investigation to implementation with a new objective. /clear removes accumulated conversation state so stale assumptions do not leak into the next task.

The strongest rule: if you would open a new ticket, clear the session. Long-lived context helps when the task is continuous. It hurts when the goal changes.

Set /model and /effort before you start

Anthropic specifically calls out setting /model and /effort before starting work to preserve prompt cache behavior. This matters because changing model or effort midstream can disrupt caching patterns and make the session more expensive or less predictable.

Use premium models and higher effort for hard reasoning: architecture decisions, cross-file refactors, concurrency bugs, security-sensitive changes, and migration planning. Use lower effort or low-thinking sessions for mechanical edits, formatting, small tests, and straightforward documentation updates.

@-mention files instead of naming them

Do not say “look at the auth middleware” and hope the agent resolves it correctly. Use @path/to/file.ts. File mentions anchor the agent to exact repository artifacts, reducing wasted search and mistaken assumptions.

This is especially important in monorepos where multiple files share similar names: auth.ts, middleware.ts, route.ts, handler.ts, and types.ts may exist in many packages.

Inspect /context

/context helps you see what the session is carrying. Use it before large changes, after long investigations, and before asking the model to produce a final patch. The goal is to catch pollution early: irrelevant files, old summaries, excessive tool context, or stale task notes.

Keep CLAUDE.md lean

CLAUDE.md should contain stable, high-value instructions: project commands, test conventions, architectural boundaries, code style constraints, deployment notes, and “do not touch” areas. It should not become a dumping ground for every preference, historical decision, or temporary task note.

A lean CLAUDE.md improves every session because it sits close to the front of the agent’s understanding. Treat it like an engineering interface, not a wiki.

Disable unneeded MCP servers

MCP servers are powerful, but every enabled server can add tool descriptions, permissions, and possible paths the agent must consider. Disable unneeded MCP servers for the current task. If you are fixing a local unit test, you probably do not need browser automation, CRM access, analytics, design tools, and database admin surfaces available in the same session.

/rename before /clear

Use /rename before clearing a session so you preserve a readable history of what happened. This is useful for audits, handoffs, and “what did the agent just do?” reviews. Rename sessions by ticket or outcome: BUG-184-fix-checkout-timezone, client-acme-navbar-refactor, or release-qa-aug15.

Use /compact carefully

/compact can reduce the active session footprint, but it can also compress away details that matter. Use it after a coherent phase is complete: investigation done, plan accepted, files identified. Avoid compacting in the middle of debugging when the agent is juggling stack traces, hypotheses, and exact line-level details.

Use /autocompact 200k on 1M models if needed

On 1M-context models, Anthropic suggests /autocompact 200k when needed. The practical interpretation: do not wait until the session bloats near the top of a giant context window. Auto-compacting around 200k tokens can keep long sessions manageable while preserving enough working memory for serious engineering tasks.

[stat] 200k tokens Anthropic’s suggested /autocompact threshold for long-running Claude Code sessions on 1M-context models when session growth needs control

---

7 workflows improved by disciplined Claude Code sessions

Session hygiene is not just about saving money. It expands what teams can safely delegate to coding agents.

1. Solo bug fixing with clean investigation state

A solo developer can run one focused session per bug: set the model, set effort, mention the failing test and relevant files, inspect context, implement the patch, run tests, rename, then clear. This prevents yesterday’s unrelated refactor from contaminating today’s bug fix.

Best for: founders, senior engineers, support-driven product teams.

2. Agency multi-client worktrees

Agencies often switch between similar repositories or branches. Without strict clearing and renaming, an agent can carry client-specific conventions into the wrong codebase. Session hygiene lets each worktree have a clean context, correct MCP tools, and explicit file anchors.

Best for: dev agencies, fractional CTOs, implementation partners.

3. Long-running feature implementation

For a feature that spans schema, API, UI, tests, and docs, a long session can be useful. The agent can maintain the plan, decisions, and touched files. The hygiene move is to inspect /context, compact only after phases, and avoid mixing unrelated requests into the feature session.

Best for: startup teams shipping product increments.

4. Release QA and regression triage

A release manager can run a Claude Code session over failed tests, changelog diffs, and known risky files. Use lower effort for log classification and higher effort for root-cause analysis. Clear between unrelated failures so one incident does not bias another.

Best for: teams with frequent deployments.

5. Repository onboarding and architecture mapping

A developer joining a repo can ask the agent to map key modules, test commands, service boundaries, and operational risks. Keep CLAUDE.md lean, mention exact folders, and rename the session before clearing so the onboarding map can be referenced later.

Best for: new hires, consultants, acquirers reviewing a codebase.

6. Documentation and developer-experience maintenance

Claude Code can update README files, API examples, migration notes, and internal runbooks. Use low effort for straightforward doc syncs and premium reasoning only when docs require understanding cross-file behavior.

Best for: platform teams and open-source maintainers.

7. Safe refactoring across a large codebase

Large refactors benefit from persistent state, but they also punish context pollution. Use a dedicated session, set /model and /effort, @-mention entry points, inspect /context, compact between stages, and clear when switching to a different refactor.

Best for: teams modernizing legacy services or migrating frameworks.

---

Workflow 1: Solo bug fixing session you can copy

Use this workflow when you have a failing test, production error, or user-reported bug. The goal is a focused session that moves from evidence to patch without accumulating unrelated context.

Step 1: Start clean and set the model

If the previous session was unrelated, run:

/rename BUG-218-checkout-coupon-rounding

Then:

/clear

Set your model and effort before the first substantive prompt:

/model claude-sonnet-5
/effort high

Use high effort for bugs involving money, auth, concurrency, data loss, or multiple services. Use low effort for obvious UI defects or simple validation bugs.

Step 2: Anchor the agent with exact files

Instead of saying “check the coupon logic,” mention the files:

Please investigate the rounding bug in @src/checkout/coupons.ts, @src/checkout/totals.ts, and @tests/checkout/coupons.test.ts. The failing case is "percentage coupon with tax-inclusive pricing". First explain the likely cause, then propose the smallest safe patch.

This reduces repository wandering. The agent starts with the relevant source and test files instead of searching through every checkout-related symbol.

Step 3: Ask for an investigation plan before code

Use a two-phase instruction:

Do not edit files yet. First identify the exact function and test path. Then list the minimum files that need changes.

This is a context-control move. It keeps the session from generating premature patches that later need to be undone.

Step 4: Inspect context before implementation

After the agent investigates, run:

/context

Look for irrelevant files, stale summaries, or broad search results. If the context is clean, continue. If it is polluted, ask the agent to summarize the confirmed facts, then /clear and restart with only the confirmed files and facts.

Step 5: Implement the smallest patch

Prompt:

Apply the smallest patch that fixes the failing test. Do not refactor unrelated checkout code. Add or update one regression test that would have caught this bug.

For bug fixing, the “smallest patch” instruction is more than style. It limits token use, review scope, and regression risk.

Step 6: Run tests, then rename and clear

After tests pass:

/rename BUG-218-fixed-coupon-rounding

Ask for PR notes:

Write a concise PR summary with root cause, fix, test coverage, and risk.

Then:

/clear

The final clear prevents the bug’s assumptions from leaking into the next task.

---

Workflow 2: Agency multi-client worktrees without context leaks

Agencies and consultants have the highest risk of Claude Code session contamination because client projects often look similar: same framework, same folder names, same build tools, different conventions. The fix is strict session boundaries.

Step 1: Create one worktree per client task

Use separate Git worktrees or clean branches:

clients/acme/BUG-91-navbar
clients/zenly/FEAT-44-billing-export

Do not reuse a single Claude Code session across clients. Even if the codebases are similar, the business rules are not.

Step 2: Disable irrelevant MCP servers

Before starting, disable tools not needed for the client task. For a frontend bug, keep local repo tools and maybe browser automation. Disable CRM, analytics, unrelated databases, and other client-specific MCP servers.

This reduces risk and reduces tool-choice noise.

Step 3: Set model and effort before context loads

For a routine client UI task:

/model claude-sonnet-5
/effort low

For a cross-service billing bug:

/model claude-opus-5
/effort high

The important part is setting both before the actual work begins.

Step 4: Load only client-specific instructions

Keep CLAUDE.md lean and stable. Put temporary task details in the prompt, not the global instruction file. A good client CLAUDE.md includes:

Section	Include	Avoid
Commands	Test, lint, build commands	Full deployment history
Style	Naming and formatting rules	Personal preferences from every reviewer
Architecture	Service boundaries	Long product roadmap notes
Safety	Files not to touch	Old one-off warnings
Client rules	Stable domain constraints	Temporary ticket commentary

Step 5: Use exact file mentions and ticket IDs

Prompt:

For ACME ticket BUG-91, inspect @apps/web/src/components/NavBar.tsx, @apps/web/src/routes/account.tsx, and @tests/e2e/navbar.spec.ts. Do not apply conventions from other clients. First identify why the account menu fails on mobile.

The phrase “Do not apply conventions from other clients” is useful, but the real protection comes from /clear, separate worktrees, and exact file mentions.

Step 6: Rename before clearing

When the task is done:

/rename ACME-BUG-91-navbar-mobile-fixed

Then:

/clear

Now your history remains auditable without carrying active context into the next client.

Step 7: Keep reusable agency knowledge outside the session

If you have reusable agency patterns, store them in templates or checklists, not in a long-lived Claude Code session. Sessions should be task-local. Process should live in your team documentation.

---

Model choice and cost: premium reasoning vs cheaper fallback

The best Claude Code model is not always the most expensive model. Use premium reasoning for tasks where mistakes are expensive, and cheaper models for routine edits. Based on current AI Cost Check pricing, here are practical options.

Model	Input / Output price per 1M tokens	Context	Best use in coding-agent workflows
Claude Opus 5	$5 / $25	1M	Complex architecture, high-risk refactors, hard debugging
Claude Sonnet 5	$2 / $10	1M	Default Claude Code workhorse for most engineering tasks
Claude Haiku 4.5	$1 / $5	200k	Fast simple edits, docs, small tests, low-risk maintenance
GPT-5.2	$1.75 / $14	1M	Alternative premium general coding and review workflows
GPT-5 mini	$0.25 / $2	500k	Cheaper fallback for mechanical edits and batch reviews
DeepSeek V3.2	$0.28 / $0.42	128k	Very low-cost fallback for simple code explanation and transforms
Gemini 3 Flash	$0.5 / $3	1M	Budget large-context scanning, doc sync, lightweight triage

A typical focused coding-agent task might consume 80k input tokens and 12k output tokens after file reads, tool calls, planning, patches, and test iteration. At that size:

Model	Estimated cost per task	Cost per 1,000 tasks
Claude Opus 5	$0.70	$700
Claude Sonnet 5	$0.28	$280
Claude Haiku 4.5	$0.14	$140
GPT-5 mini	$0.044	$44
DeepSeek V3.2	$0.027	$27
Gemini 3 Flash	$0.076	$76

That estimate uses the published per-token prices: input cost plus output cost. Real Claude Code sessions can be smaller for isolated changes or much larger for multi-hour refactors. Long-running sessions with repeated file inspection and broad tool use can reach 200k-600k input tokens and 20k-80k output tokens.

For monthly planning, use task volume:

Team pattern	Tasks per month	Recommended default	Estimated monthly range
Solo founder	100-250	Claude Sonnet 5 + Haiku fallback	$20-$120
Small product team	500-1,500	Sonnet default, Opus for hard tasks	$150-$900
Dev agency	1,000-4,000	Sonnet per client worktree, Haiku for docs	$300-$2,500
Enterprise platform team	5,000-20,000	Routed stack with strict hygiene	$1,500-$12,000+

Use AI Cost Check to model your own mix across input tokens, output tokens, and task volume. For broader model tradeoffs, compare GPT-5 vs Claude Opus 4.6 or GPT-5 vs Gemini 3 Pro.

When premium models are worth it

Use Claude Opus 5 or another premium model when the task requires deep reasoning across many files, subtle domain constraints, or high-risk production behavior. Examples: billing logic, permissions, data migrations, security boundaries, distributed systems, and large refactors.

When premium models are overkill

Use cheaper models for predictable work: updating tests after an accepted patch, formatting code, generating docs from existing files, writing simple CRUD endpoints, classifying test failures, or applying a repeated pattern across files.

When to use higher effort vs low or zero-thinking sessions

Use higher effort for tasks where the plan matters more than the edit: root cause analysis, architecture, migrations, test strategy, and security review. Use low or zero-thinking modes for tasks where the target is already known: rename a prop, update examples, generate fixtures, summarize a diff, or apply an approved patch.

---

How to design a Claude Code session policy for your team

A team policy should be short enough that developers follow it. The goal is not bureaucracy. The goal is repeatable agent quality.

The 10-rule session policy

1. Start every ticket from a clean session unless it continues the same task.
2. Run /model and /effort before the first real prompt.
3. Use /clear between unrelated tasks.
4. Use /rename before /clear.
5. @-mention exact files whenever possible.
6. Inspect /context before large edits and before final PR summaries.
7. Keep CLAUDE.md under control and remove temporary notes.
8. Disable unneeded MCP servers before focused work.
9. Use /compact only after a completed phase.
10. Use /autocompact 200k on 1M-context models for long sessions that need guardrails.

Recommended CLAUDE.md structure

A lean CLAUDE.md should fit on a screen or two. Use headings like:

• Project overview: one paragraph
• Commands: install, test, lint, build
• Architecture boundaries: what lives where
• Code conventions: naming, typing, error handling
• Testing rules: unit vs integration expectations
• Safety constraints: files, migrations, production data
• PR checklist: summary, tests, risk

Remove anything temporary. If a note applies to only one ticket, put it in the session prompt or the ticket, not CLAUDE.md.

A reusable starting prompt

Use this template:

We are working on [ticket]. Use [model/effort already set]. Relevant files are @file1, @file2, and @file3. First inspect the files and explain the minimal plan. Do not edit until I approve. Keep the change limited to this ticket. Before final output, summarize tests run and remaining risk.

This prompt works because it defines scope, anchors files, delays edits, and sets the expected final artifact.

---

Risks, limits, and when not to use long-running coding agents

Long-running coding agents are powerful, but they are not the right interface for every task.

Do not use a long session for unrelated microtasks. If you have five tiny independent edits, run five clean sessions or use a cheaper batch process. Do not use high effort for mechanical changes. Do not leave sensitive MCP servers enabled “just in case.” Do not let CLAUDE.md become an unreviewed policy layer that silently affects every code change.

Be careful with /compact. A compacted session can preserve the broad story while losing exact details. If the task depends on stack traces, line numbers, failing assertions, or precise API contracts, compact after capturing those details in a file, ticket, or explicit summary.

Be careful with auto-compaction as well. /autocompact 200k is useful on 1M models when sessions grow, but it is not a substitute for clearing unrelated work. Auto-compaction manages size. It does not make irrelevant context relevant.

Finally, require human review for production changes. Coding agents can generate plausible patches quickly, but review still catches domain errors, security regressions, and product behavior mismatches. The right operating model is agent-assisted engineering, not unattended merge-to-prod for high-risk code.

---

Frequently asked questions

What is Claude Code session hygiene?

Claude Code session hygiene is the practice of keeping an agent’s working context clean, explicit, and task-specific. The core moves are /clear between unrelated tasks, set /model and /effort before work begins, @-mention files, inspect /context, and keep CLAUDE.md lean.

How much does a Claude Code task cost?

A focused coding-agent task using 80k input tokens and 12k output tokens costs about $0.28 on Claude Sonnet 5 and $0.70 on Claude Opus 5. Cheaper fallback runs can be under $0.05 on models such as GPT-5 mini or DeepSeek V3.2. Use AI Cost Check to calculate your own token mix.

When should I use /clear in Claude Code?

Use /clear whenever you switch to an unrelated task, ticket, branch, client, or subsystem. If the next prompt would belong in a different GitHub issue or client worktree, clear the session first and rename the old session before clearing.

Should I use Claude Opus 5 or Claude Sonnet 5 for coding agents?

Use Claude Sonnet 5 as the default for most Claude Code work because it has 1M context and lower pricing at $2 input / $10 output per 1M tokens. Use Claude Opus 5 for high-risk debugging, architecture, migrations, and complex refactors where better reasoning is worth the higher $5 / $25 pricing.

Is /compact the same as /clear?

No. /compact compresses the current session so it can continue with less active context, while /clear starts fresh. Use /compact after a completed phase of the same task; use /clear when the task changes.

---

Build a cleaner coding-agent workflow

Anthropic’s Claude Code guidance is a clear signal: as coding agents run longer, the teams that win will manage context deliberately. Start with a simple policy: set /model and /effort first, @-mention files, inspect /context, rename and clear between tasks, and reserve premium reasoning for work that justifies it.

To estimate your own Claude Code budget, run scenarios in AI Cost Check. For model selection, review Claude Sonnet 5, Claude Opus 5, and lower-cost fallbacks like GPT-5 mini. If you are comparing premium coding stacks, start with GPT-5 vs Claude Opus 4.6 and Claude Opus 4.6 vs Gemini 3 Pro.