Try free

Last updated 13 October 2026

Limit Claude Code to a specific folder

Large repositories create unnecessary context noise

Starting a session at the root of a massive monorepo often causes Claude Code to spend unnecessary tokens indexing files you do not need. If you are working on a specific microservice or a frontend component, the agent might waste time reading configuration files from unrelated parts of the tree. This slows down the initial response and consumes your context window with irrelevant metadata. The agent tries to be helpful by understanding the whole project, but this wide scope can lead to confusion about dependencies that are not relevant to your current task.

When the context window fills up with headers from every folder in your project, the agent might start proposing changes that break things in other modules. You want the agent to focus on the logic in front of you, not the build scripts for a legacy service five folders away. Restricting the scope is the most effective way to keep the cost down and the quality of the edits high. By narrowing the focus, you ensure that the agent remains an expert on the specific code you are touching right now.

Start the session inside the target directory

The most direct way to limit the scope is to navigate into the specific folder before running the claude command. When you run claude from a subdirectory, the agent treats that directory as its primary workspace. It still has the ability to look up if it needs to find a root configuration, but it focuses its Read and Glob tools on the current path. This simple change significantly reduces the noise in the early stages of a session because the agent assumes the relevant work is local to the current working directory.

If you need to switch to a different part of the project, it is often better to quit the current session and start a new one in the other folder. You can use the claude command with various flags to manage these sessions, but staying physically in the folder you want to edit is the strongest signal you can give the agent. If you find yourself needing to jump back and forth between two distinct folders, consider running two separate terminal windows to keep the context for each task isolated.

Use local instructions for directory specific behavior

You can place a CLAUDE.md file in any subdirectory to give the agent specific rules for that part of the project. While the root CLAUDE.md file handles global project standards, the local version allows you to define folder specific patterns. You might specify that in this folder, the agent should only use certain libraries or follow a particular naming convention. This file helps the agent stay within the boundaries of the local architecture without you having to repeat those instructions in every prompt.

These local instructions are particularly useful for defining how the agent should use the Bash or Edit tools within that scope. For example, you can tell the agent that all tests in this folder must be run with a specific command that is different from the root test suite. When the agent reads the CLAUDE.md file in its current path, it prioritizes those instructions over more general ones it might have found elsewhere. This creates a virtual fence around the folder logic.

Restrict file visibility with ignore files

Claude Code respects the .gitignore file by default. If there are massive build directories, node modules, or legacy code folders that the agent should never touch, ensure they are listed in your .gitignore file. This prevents the Glob tool from returning those files and stops the agent from attempting to Read them. This is a global way to ensure the agent does not waste time indexing compiled assets or temporary files that would only clutter the context window.

If you have files that you want to keep in the repository but hide specifically from the agent, you can check your configuration to see how it handles hidden files. The agent is designed to avoid files that the developer has explicitly told the version control system to ignore. This keeps the agent from accidentally suggesting edits to generated code or huge data files that would crash the session. Managing your ignore patterns is one of the best ways to keep the agent focused on your source code.

Configure permissions for tool usage

The .claude/settings.json file allows you to define permissions for different tools. You can set up the agent to require explicit approval before it uses the Write tool in certain areas. By adjusting the permissions object in your settings file, you can ensure that the agent remains in a plan mode or asks for confirmation for every edit. This provides a safety net when you are working in a sensitive part of the codebase where accidental changes to neighboring files could be destructive.

You can also use the /permissions command inside a session to see what is currently allowed. If you notice the agent trying to access files outside your desired scope, you can switch the mode using Shift+Tab to cycle through default, acceptEdits, plan, and bypassPermissions. By staying in plan mode, you can see exactly which files the agent intends to touch before it actually performs any work. This manual oversight is a great way to enforce a folder scope during a complex task.

Manage several scoped sessions with adhdTerminal

When you work on a complex project, you often need to handle a backend fix and a frontend update at the same time. Running multiple terminal windows can become chaotic as you lose track of which session is doing what. adhdTerminal solves this by running many Claude Code sessions side by side as tiles on a wall. Each tile can be pinned to a specific folder and given a name like API or UI, allowing you to see if a session is working or waiting for you at a glance.

Each tile in adhdTerminal saves its location and state, so when you restart the app, your folder scoped sessions are exactly where you left them. This is helpful for developers who need to jump between different parts of a monorepo without losing the specific context of each folder. The app also has a free iPhone mirror that lets you check the status of these scoped tiles or send a quick task while you are away from your desk, keeping the work moving even when you are not at your computer.

Refine searches using tool specific commands

When you are inside a session, you can prompt the agent to use the Grep or Glob tools on specific patterns. Instead of asking it to find a function everywhere, tell it to search only within a specific path relative to your current location. If the agent starts to wander into other folders, you can use a prompt to remind it of its current scope. This keeps the conversation focused on the files that matter for the current task and prevents the agent from reading unnecessary context.

Using the /add-dir command can also help if you want to bring a specific neighboring folder into view without opening the entire root. This command allows you to be surgical about which directories are added to the agent's context. By only adding the specific folders you need, you maintain a lean session that responds faster and uses fewer tokens. This manual control over the folder scope is often more effective than relying on the agent to guess what is relevant.

Clear or compact the session to remove unwanted context

If the agent has read too many files from outside your target scope, the context window can become cluttered. Use the /compact command to summarize the conversation and free up space. This removes the detailed content of those extra files while keeping the important progress. It is a good way to trim the fat if the agent has gone on a long search through the wrong directories and you want to bring its focus back to the current folder.

If the session has gone completely off track into the wrong directories, the /clear command will start the conversation over in the same folder. This gives you a fresh start without the old file history or previous search results. Starting over with /clear is often faster than trying to talk the agent out of a bad path. It ensures that the very next prompt starts with a clean slate, focused entirely on the directory where you initiated the command.

Use subagents for isolated subtasks

You can define specialized agents by creating markdown files in the .claude/agents directory. These subagents can be designed to handle very specific types of work, such as documentation or unit testing for a single folder. When you use the /agents command to invoke one, you are essentially delegating a portion of the work to a focused process. This helps keep the main session clean and ensures that the heavy lifting in specific directories is handled by an agent with the right instructions.

Subagents can have their own set of rules that are even more restrictive than your main CLAUDE.md. By defining a subagent for a specific folder, you create a dedicated tool that knows exactly what its boundaries are. This is a powerful way to manage complex repositories where different folders have vastly different requirements. It allows you to maintain a high level of precision without cluttering your primary interaction with the main claude session.

Questions people ask

Can I prevent the agent from reading any file outside my current directory?

You cannot strictly lock the agent inside a folder using only the claude command if those files are visible to the shell. The most effective way is to start the session in that folder and use a local CLAUDE.md to tell the agent to stay put. If you need absolute isolation, you would need to use OS level permissions or a container.

What happens if I use /add-dir on a folder that is already in my scope?

The /add-dir command tells the agent to index and pay attention to a specific path. If you are already in that folder, it reinforces the focus on those files. It is useful when the agent seems to be ignoring certain files that you know are relevant to the task.

How do I see which files the agent has already read?

You can use the /status command to get an overview of the current session state. This helps you identify if the agent has loaded files from outside your intended scope. If you see irrelevant files in the list, it is a good time to use /compact or /clear.

Read next

More on claude code basics·All posts