Try free

Last updated 13 October 2026

Resolve context limit errors in Claude

Identifying the context wall

Your terminal session stops and an error message appears. Claude Code informs you that the context limit is reached. This happens because the agent keeps a record of every file it reads and every response it generates. When the conversation grows too long or the codebase is too large, the agent loses the ability to process new information. You might notice the agent becoming less accurate or failing to complete a Bash command before the limit hits.

The context window is a limited space that holds the entire history of your current interaction. Every time the agent uses the Read tool to look at a file, that file content stays in the memory for the rest of the session. If you are working in a large repository, it is easy to accidentally fill this space by asking the agent to search through too many directories. Once the window is full, the agent cannot see the earliest parts of your conversation or read any more files.

Compact the conversation history

The /compact command is your first line of defense against a full context window. When you run this command inside a session, Claude Code creates a summary of the conversation so far. It then replaces the verbose history with this condensed version. This action frees up significant space in the context window. You should use this command when you have finished a sub-task but want to keep working on the same problem in the same session.

This summarization process is intelligent. It keeps the core progress and the current state of the project while discarding the raw text of previous file reads and long error logs. By running /compact regularly, you can sustain a long working session without needing to restart. It is a good habit to trigger this command after every major milestone in your task to ensure the agent has enough room to handle the next steps.

Strategic file reading practices

Large files are the main cause of context exhaustion. The Read tool pulls the entire content of a file into the session. If you ask the agent to examine ten large source files, your context window will fill up immediately. Instead of reading every file, you should encourage the agent to use the Grep tool or the Glob tool to find specific lines. This keeps the agent from loading unnecessary text that it will just have to remember later.

You can also guide the agent to be more selective. If you know exactly where a bug is, tell the agent the specific file path and line number. This prevents the agent from searching the entire tree with the Read tool. If the agent tries to read a large log file or a minified javascript bundle, you can press Escape to interrupt the process. This stops the agent before it fills the context with junk data that is not useful for the task.

Project instructions as context anchors

Project instructions in CLAUDE.md help manage context efficiently. Instead of explaining your coding style in every prompt, put those rules in the root CLAUDE.md file. Claude Code reads this file automatically at the start of a session. By providing clear guidance here, you reduce the need for long, repetitive prompts that eat into your token budget. You can also place a CLAUDE.md file in a specific subdirectory to give the agent local context without cluttering the global session.

The root CLAUDE.md should contain high-level information like the build command and the test command. It should also describe the core architecture. If the agent knows these things from the start, it does not have to spend tokens asking you for clarification or reading configuration files to figure them out. A well-maintained CLAUDE.md acts as a permanent memory that does not get cleared when you use the /compact command, making it the most efficient way to store project-specific knowledge.

Starting fresh with session commands

Sometimes a session is too far gone for a summary to be effective. Use the /clear command to wipe the current conversation history while staying in the same project folder. This is useful when you have finished one feature and are moving on to something completely unrelated. Starting with a clean context ensures that old, irrelevant code from the previous task does not confuse the agent or waste space in the current task.

If you need to reference a previous session, you can exit the agent with Ctrl+C and run claude --resume to see a list of earlier interactions. This allows you to start fresh with a clean slate while keeping your previous work as a reference you can return to if needed. You can also use claude --continue to quickly jump back into the most recent session if you accidentally closed your terminal. Managing these sessions separately helps keep each task focused and within the token limits.

Managing parallel sessions with adhdTerminal

Managing complex tasks across multiple windows prevents context bloat. adhdTerminal is useful here because it lets you run several Claude Code sessions side by side as tiles. You can dedicate one tile to a backend refactor and another to a frontend fix. Each tile maintains its own separate context window. This prevents the backend session from being cluttered with frontend code, which keeps both sessions faster and more responsive.

The app also helps you keep track of which session is which. Each tile can have a unique name and color, making it easy to jump between tasks without losing your place. If a session in one tile reaches its context limit, you can /compact it or /clear it without affecting the work happening in your other tiles. This visual organization is especially helpful for developers who need to monitor long-running tasks or coordinate changes across different parts of a system simultaneously.

Configuring file exclusion and settings

The .gitignore file and the settings.json file are essential tools for context management. Claude Code respects .gitignore by default, which means it will not look at files you have excluded from version control. If your build artifacts or dependency folders like node_modules are not ignored, the agent might accidentally read them. This wastes tokens on generated code or library files you do not intend to edit.

You can also refine permissions in .claude/settings.json. Under the permissions key, you can specify which tools the agent is allowed to use and whether it needs to ask for your consent. If you find the agent is using the WebFetch tool too often and pulling in massive amounts of external documentation, you can adjust these settings. Restricting the agent from reading certain directories or using certain tools can preserve your context for the actual code you are writing.

Monitoring session status and permissions

The permission modes also play a role in how context is consumed. Use Shift+Tab to cycle through modes like plan or acceptEdits. In plan mode, the agent describes what it will do without executing every step immediately. This can help you catch a runaway process that might try to read too many files. By reviewing the plan first, you can tell the agent to ignore certain files before it actually reads them into the context.

If you are using adhdTerminal, you can see the working status of each tile on your wall, which helps you identify if a session is hung because of a context limit before you even switch to that window. Monitoring your session health is also a good practice inside the terminal. Use the /status command to see the current state of the agent and the /usage command to see how many tokens have been consumed. Checking the cost with /cost can also give you an idea of how much data is being processed.

Modular tasks with subagents and commands

If you find yourself frequently hitting limits in a massive repository, consider using subagents or custom commands. Subagents are defined in .claude/agents as markdown files. A subagent can be triggered to handle a specific part of a task with its own instructions. Because a subagent can be focused on a very narrow scope, it does not necessarily need the full history of your main session to be effective.

Custom commands in .claude/commands can also help. You can create a command that tells the agent exactly which files to read and what steps to take for a common task. This prevents the agent from wandering through the file system and filling the context window with irrelevant information. By structuring your project with these tools, you turn a large, unmanageable task into a series of small, context-efficient steps that Claude Code can handle without error.

Questions people ask

What happens if I ignore the context limit?

The agent will eventually stop responding or produce incomplete code blocks. It may also forget previous instructions or the state of the files it just edited, leading to errors in the code it writes.

Can I manually remove a file from the context?

There is no specific slash command to un-read a file. You must use /compact to summarize the session or /clear to start over with a fresh context window to remove specific file contents from the agent's memory.

Does the agent remember my CLAUDE.md after a /clear?

Yes, Claude Code reads CLAUDE.md at the start of every session. Running /clear resets the conversation history, but the agent will still follow the instructions in your project files when you send your next prompt.

Read next

More on when it goes wrong·All posts