Claude Code Session Limits: How to Keep Context Small

You typed a five-word prompt, yet Claude Code hit a session limit again. The prompt isn't the whole request. Claude may also process earlier messages, files, tool definitions, and terminal output on every turn.

The lasting fix is to control what enters the session, when context gets cleared, and which work deserves its own session.

Prerequisites

• A working Claude Code installation
• Access to the project directory from a terminal
• Permission to change enabled MCP servers and Claude Code settings
• A current task that can be divided into clear checkpoints

1. Clear context between unrelated tasks

Finish the current task, save any needed changes, then run:

textCopy
/clear

Context is the material Claude can consider during a request. It may include the conversation, system instructions, tool descriptions, selected files, command output, and generated analysis.

Running /clear removes the old conversation from future requests. It doesn't delete project files or undo changes written to disk.

That makes /clear useful after a completed bug fix, documentation update, refactor, or investigation. It's even more useful before switching to unrelated work.

A session that starts with authentication debugging shouldn't continue into database schema design. Old logs, hypotheses, and file contents can stay attached to later requests even when they no longer help.

Use a restart prompt after clearing

After /clear, give Claude a compact description of the next task:

textCopy
Task: [SPECIFIC TASK]

Relevant files:
- [FILE PATH]
- [FILE PATH]

Constraints:
- [CONSTRAINT]
- [CONSTRAINT]

Done when:
- [TESTABLE COMPLETION CONDITION]

Do not inspect unrelated directories unless required.

This prompt replaces accumulated conversational context with a small, explicit working set. It also reduces exploratory file reads that can pull unnecessary code into the session.

The completion condition matters. Without it, an agent may keep investigating, testing, and revising after the useful work is already complete.

Preserve sessions that may matter later

Name important work before leaving it:

textCopy
/rename

Use a descriptive name tied to the result, such as checkout-timeout-investigation or postgres-migration-plan. A meaningful name makes later recovery easier than searching through unnamed sessions.

Resume a saved session only when its history still helps:

textCopy
/resume

Continuity has a cost. Resuming makes sense when prior decisions, test results, and rejected approaches would otherwise need to be reconstructed.

Use rewind when later conversation has become noisy or incorrect:

textCopy
/rewind

/rewind returns work to an earlier point without carrying all later conversation forward. This is useful after a long dead-end investigation or an instruction that sent the session in the wrong direction.

2. Choose the model and processing mode before work starts

For a small, isolated job, start a separate session with a lower-cost model:

bashCopy
claude --model haiku

Haiku works well for tasks such as classifying errors, summarizing a short file, renaming identifiers, or drafting focused tests. Larger reasoning tasks may justify a more capable model.

Choose the model, effort level, and fast mode at the beginning of the session. Keep those settings stable while the session remains active.

Claude Code can use prompt caching, which avoids processing identical context from scratch when cached material remains valid. Changing model or processing settings mid-session may invalidate that cache.

When this happens, the next request can process much more of the conversation again. The visible prompt stays short, but the effective input becomes large.

Use this pattern when the main session encounters a minor side task:

bashCopy
cd /path/to/project
claude --model haiku

Then give the new session only the required material:

textCopy
Inspect src/auth/token.ts. Find the branch that returns an expired token.

Return:
1. The responsible function
2. The condition that triggers the bug
3. A minimal patch

Do not inspect other directories unless this file imports relevant logic.

The separate session has no inherited discussion, command history, or unrelated files. Its context starts near zero and grows only around the delegated task.

Model selection is a trade-off. A smaller model lowers cost for straightforward work, while a larger model may finish complex reasoning with fewer failed attempts. The better measure is total work processed, not price per individual request.

3. Stop terminal output from becoming permanent context

Replace unrestricted build output with a filtered command:

bashCopy
npm run build > /tmp/build.log 2>&1 || {
tail -n 80 /tmp/build.log
exit 1
}
echo "Build completed successfully"

This command stores the full log outside the conversation. Claude sees one success line or the final 80 lines when the build fails.

Without filtering, package installation, compilation, test, and container commands can print hundreds or thousands of lines. That output may remain available to later turns and be processed repeatedly.

A useful tool response answers three questions: Did the command succeed, what failed, and where can the full log be found? It doesn't need to replay every successful operation.

For test suites, report only failures:

bashCopy
pytest -q --tb=short > /tmp/pytest.log 2>&1 || {
grep -A 20 -B 5 -E "FAILED|ERROR|Traceback" /tmp/pytest.log | tail -n 160
exit 1
}
echo "Tests passed"

The output cap prevents one cascading failure from flooding the session. The complete log remains in /tmp/pytest.log for targeted inspection.

Git output benefits from the same treatment:

bashCopy
git status --short
git diff --stat
git diff -- src/auth/token.ts

git diff without a path can inject an entire repository change set. Start with the summary, then request only the file or hunk needed for the current decision.

Wrap noisy commands in project scripts

Create a small script when the same noisy operation runs often:

bashCopy
#!/usr/bin/env bash
set -o pipefail
LOG_FILE="${TMPDIR:-/tmp}/project-build.log"
if npm run build >"$LOG_FILE" 2>&1; then
echo "PASS: build"
else
echo "FAIL: build"
tail -n 100 "$LOG_FILE"
exit 1
fi

Saving this as scripts/build-brief.sh standardizes compact output for developers, CI jobs, and coding agents. The script also keeps failure details available without loading the complete log into Claude's context.

Ask Claude to use the compact script:

textCopy
Run scripts/build-brief.sh. If it fails, inspect only the reported errors first.
Read the complete log only when those errors are insufficient.

This creates an output budget. Full logs become an exception instead of the default.

4. Reduce MCP and tool instructions

Check the current context before enabling more integrations:

textCopy
/context

The context view helps reveal how much space is occupied by conversation, tools, files, and other session material. Run it after connecting a new tool or when a session becomes unexpectedly expensive.

Model Context Protocol, or MCP, connects Claude Code to external tools and data sources. An MCP server might expose issue trackers, databases, browsers, source control, monitoring systems, or internal APIs.

Each connected server can add tool names, schemas, instructions, and documentation. A tool doesn't need to run to consume context if its full definition is loaded at session start.

Keep only servers required for the current task enabled. A frontend CSS fix rarely needs database administration, incident management, and cloud deployment tools at the same time.

Prefer tools marked deferred when available. Deferred loading keeps large schemas outside the active context until the tool is actually needed.

For example, a database MCP server may expose many operations and detailed parameter schemas. If the task only edits static documentation, those definitions have no value but can still increase every request.

Inspect MCP configuration when /context shows a large tool allocation. The Model Context Protocol documentation explains how servers expose capabilities and connect to clients.

5. Delegate only when the returned summary will be reused

Use a sub-agent for a bounded research task:

textCopy
Review the files under src/payments/providers/. Return no more than 400 words covering:
- Provider interface
- Retry behavior
- Error mapping
- Shared dependencies
- The three files most relevant to adding a new provider

Do not propose code changes.

A sub-agent can process a large body of material and return a small summary to the main session. This is valuable when that summary will guide several later decisions.

Delegation doesn't remove token usage. It moves part of the work into another agent or session. The total can increase if the sub-agent reads many files, generates a long response, and the parent then repeats the investigation.

Savings appear only when the compact result replaces repeated access to the larger source material.

Use Haiku for simple delegated tasks such as file classification, focused extraction, or short summaries. Complex architecture analysis may need a stronger model, especially when mistakes would trigger more work.

Skip delegation when the parent needs one small fact and will end immediately afterward. Starting another agent adds instructions, tool calls, and a return message for little reuse.

A practical decision test is simple:

Keep the return format strict. A sub-agent that returns pages of prose simply transfers its large context back into the parent session.

6. Control background work and large inputs

Before attaching a document, convert it to plain text when layout doesn't matter:

bashCopy
pdftotext architecture-review.pdf /tmp/architecture-review.txt
wc -l /tmp/architecture-review.txt
sed -n '1,220p' /tmp/architecture-review.txt

This workflow measures the document before loading it. It also permits selective reading instead of submitting the entire PDF.

Screenshots and PDFs can consume more input than equivalent plain text. Images require visual processing, while PDFs may combine text, layout, embedded fonts, and graphics.

Reserve screenshots for genuinely visual defects, such as spacing, clipping, colors, or chart rendering. For stack traces, configuration, and logs, paste text instead.

Use a narrow request with long documents:

textCopy
Read /tmp/architecture-review.txt. Inspect only sections related to:
- Authentication boundaries
- Secret storage
- Token rotation

Return a maximum of 12 bullet points.
Include source section names for every finding.

The scope stops Claude from treating the complete document as equally important. Source section names preserve traceability without returning large quotations.

Scheduled tasks and background agents need the same discipline. Review recurring jobs and disable work that no longer supports an active goal.

Avoid attaching an old, large session to a frequent background task. Repeated jobs can process stale history every time they run, and long intervals may reduce available cache benefits.

For each recurring task, record:

textCopy
Task: [BACKGROUND TASK]
Frequency: [SCHEDULE]
Required inputs: [FILES OR DATA]
Maximum output: [LINES OR WORDS]
Stop condition: [SUCCESS CONDITION]
Session policy: Start fresh unless continuity is required

This template separates durable task instructions from historical conversation. It also places a visible ceiling on each run's response.

7. Monitor context before the limit becomes a surprise

Run these commands at natural checkpoints:

textCopy
/context

textCopy
/usage

textCopy
/cost

/context shows what occupies the current context window. It's the first check when a session feels large despite short prompts.

/usage helps track consumption during an active session. Run it after broad codebase searches, large document reads, or tool-heavy work.

/cost gives cost information where supported by the current Claude Code setup and account type. Compare it before and after expensive operations instead of waiting until the task ends.

A useful checkpoint routine is:

textCopy
1. Run /context before a broad investigation.
2. Complete one bounded unit of work.
3. Run /usage and /cost.
4. Save conclusions to a project file.
5. Run /clear before unrelated work.

Saving conclusions to disk matters. Conversation memory is expensive and temporary, while a concise project note can be loaded only when required.

Use a checkpoint file such as docs/claude-checkpoint.md:

markdownCopy

## Objective

[CURRENT OBJECTIVE]

## Confirmed findings

- [FINDING]
- [FINDING]

## Decisions

- [DECISION AND REASON]

## Remaining work

- [NEXT ACTION]

## Relevant files

- `[FILE PATH]`

This file turns a long conversation into a small, reviewable artifact. A fresh session can read it without replaying every failed command and discarded hypothesis.

For broader infrastructure cost limits, the same context budgeting principle applies to hosted services. The guide to Cloudflare Workers costs and limits shows how hidden execution constraints shape architecture choices.

Testing and next actions

Testing Your Implementation

Create one controlled session and record its baseline:

textCopy
/clear

textCopy
/context

Then run one noisy command normally, inspect /context, clear again, and run the filtered version. Compare how much command output enters the session.

Next, enable only one required MCP server and check context again:

textCopy
/context

Repeat after enabling another server. This exposes the context cost of each integration without relying on assumptions.

Finally, complete two unrelated tasks. Continue in the same session for the first test, then use /clear between tasks for the second. Compare /usage and /cost at the same checkpoints.

Exact values depend on the model, account, cache state, and task, but the smaller-context pattern should be visible.

Troubleshooting common Claude Code session problems

If /clear seems to lose important knowledge, the session lacked a durable checkpoint. Save confirmed findings and decisions to a small Markdown file before clearing.

If usage jumps after changing models, prompt cache invalidation may have caused prior context to be processed again. Keep the original session stable and open a separate session for the alternate model.

If /context shows a large tool allocation, disable unrelated MCP servers. Prefer deferred tools when the server supports them.

If command output dominates context, redirect full logs to a file and print only errors. Don't ask Claude to rerun the same verbose command before checking the existing log.

If a sub-agent increases total usage, narrow its file scope and cap its output. Remove delegation entirely when the result will be used once.

If a PDF or screenshot produces unexpectedly high usage, extract the relevant text. Keep the original visual input only when layout or rendering affects the answer.

If recurring work consumes context, check whether each run starts with an old session. A fresh scheduled session with explicit inputs is often smaller and easier to audit.

Hands-On Steps

Start here (your first step)

Run /context in the current Claude Code session and identify the largest context category before sending another request.

Quick wins (immediate impact)

• Run /clear before the next unrelated task, then provide only relevant files and one testable completion condition.
• Replace one verbose build or test command with a wrapper that prints at most 100 failure lines.

Deep dive (for those who want more)

• Audit every enabled MCP server and disable any server not required for the current task.
• Create docs/claude-checkpoint.md, update it after each completed milestone, and start a fresh session for the next milestone.

Useful Resources

• Claude Code documentation - Official setup, concepts, workflows, and feature documentation.
• Claude Code CLI reference - Command-line options and usage details.
• Model Context Protocol - Official MCP concepts, server connections, and tool integration guidance.
• Anthropic pricing - Current model pricing and plan information.

Key Takeaways

Claude Code session limits reflect the full processed context, not only the latest prompt. Conversation history, files, command output, tool definitions, images, and delegated work all contribute.

Use /clear between unrelated tasks. Use /rename, /resume, and /rewind when continuity is valuable, rather than keeping every task in one growing session.

Choose the model, effort level, and fast mode before beginning substantial work. For small side tasks, start a separate Haiku session instead of changing an active session.

Filter shell output, keep full logs on disk, and load only relevant failures.

Disable unused MCP servers and prefer deferred tools when available.

Delegate large, reusable investigations, not one-line lookups.

Convert PDFs and screenshots to plain text when visual structure doesn't matter.

Check /context, /usage, and /cost throughout long work.

Small sessions aren't created by shorter prompts alone. They come from strict boundaries around history, tools, output, and task scope.