Try free

Last updated 13 October 2026

How to give Claude Code project context

Context issues in the terminal

Developers often find that a coding agent misses the big picture of a large repository. You start a session and the agent tries to fix a bug but lacks knowledge of your custom build system or specific naming conventions. It might suggest a library you do not use or ignore a utility class that already exists. This leads to wasted tokens and incorrect code that you have to fix manually. The solution is not to feed it every file at once but to provide a map it can follow.

Effective context starts with clear entry points. Claude Code uses specific files to understand what it should do and how it should behave. If you do not provide these files, the agent relies on its general training which might not match your project requirements. You need a strategy that covers global rules, project-specific logic, and your personal workflow preferences. This guide explains how to set up those layers so the agent works with your code instead of against it.

Without a structured approach, the agent might spend most of its time using the Glob and Grep tools just to figure out where your source files live. This consumes your time and your budget. By setting up documentation files and configuration files in the correct places, you reduce the discovery phase. You allow the agent to focus on solving the actual problem rather than guessing how your repository is organized.

The primary instruction file

The most important tool for project context is the CLAUDE.md file in your repository root. This file acts as the manual for the agent. It should contain a high-level summary of the project purpose and the technical stack. List the primary languages, frameworks, and any architectural patterns you follow. If your team uses specific naming conventions for variables or files, write them down here. The agent reads this file at the start of a session to align its behavior with your codebase.

A good root CLAUDE.md also includes common commands for building and testing. Use this space to define what a successful build looks like and which test suites are relevant for different parts of the app. You can specify whether the agent should prefer certain libraries over others. For example, if you use a specific state management tool, mention it here so the agent does not suggest a different one. This file ensures that every new session starts with a consistent understanding of the repository.

You should also include a section on coding style in this file. If you prefer explicit type definitions or a specific way of handling errors, the agent needs to know. You can even list files that the agent should never touch or folders it should ignore. Because this file sits in the root of your repo, it is the first place the agent looks for guidance. Keeping it updated as your project grows is the best way to maintain high-quality interactions.

Subdirectory context for complex trees

Large projects often have different rules for different folders. A backend directory might follow strict functional programming rules while the frontend uses a specific component library. You can place a CLAUDE.md file in any subdirectory to provide localized instructions. When the agent works within that part of the tree, it combines the instructions from the root file with the ones found in the specific folder. This prevents the agent from getting confused by different styles within the same repository.

Subdirectory instructions are useful for documenting legacy code or specialized modules. If a certain folder contains performance-critical logic where the agent must avoid certain patterns, put those warnings in a local CLAUDE.md file. This keeps your root instructions clean and focused on the big picture. The agent uses its Read and Glob tools to navigate these folders, but the local markdown files act as guardrails that keep it on the right track.

This layered approach is the best way to handle massive monorepos. You can have a CLAUDE.md in the root for general architecture, another in the api folder for documentation standards, and another in the styles folder for design system rules. The agent automatically picks up the context relevant to the files it is editing. This local context helps the agent generate code that fits perfectly into the existing module without needing manual corrections.

Global and local settings configuration

Beyond project documentation, you can control the behavior of the agent through settings.json files. The file at ~/.claude/settings.json applies to every project you work on. This is where you define your global preferences, such as your favorite editor or default permission modes. If you prefer the agent to always use a specific model or start in a certain mode, you set it here. This ensures a consistent experience regardless of which repository you are currently fixing.

Inside a specific project, you can use .claude/settings.json to override global defaults for that repo. If you share this file with your team, everyone gets the same agent configuration. For your own private adjustments that you do not want to commit to version control, use .claude/settings.local.json. This file is perfect for local paths or specific permission overrides that only apply to your machine. Managing these files correctly prevents you from repeating the same setup steps every time you start the terminal.

These settings files allow you to define how the agent uses specific tools. You can set permissions for the Bash tool or the Edit tool to ensure the agent does not perform destructive actions without your consent. By centralizing these rules, you create a safer and more predictable environment. The agent checks these settings at startup and respects them throughout the session, which saves you from having to manually adjust its behavior every time you run a command.

Active exploration with built-in tools

Context is not just about static files. Claude Code uses a set of tools to actively learn about your project during a session. The Glob tool helps it find files based on patterns, which is useful for discovering the structure of a new repository. Grep allows it to search for specific strings or function definitions across the entire codebase. When you ask a question, the agent often uses these tools first to gather the facts it needs before suggesting a change.

You can guide this exploration by asking the agent to summarize a specific part of the tree or to find all instances of a certain pattern. Using the Bash tool, the agent can run your build scripts to see how the code actually behaves. This dynamic context is what makes the agent powerful. It does not just read documentation; it observes the code in action. If the agent seems lost, you can use the /status command to see what it knows or use the Read tool to show it a specific file.

The agent also records its own progress using the Task tool. This helps it keep track of what it has already accomplished and what remains to be done. By reviewing the status of these tasks, you can see if the agent has misinterpreted your instructions or missed a critical step. This feedback loop between the agent and the repository ensures that the context remains accurate as the session progresses.

Managing session history and memory

As a session grows, the context window fills up with previous exchanges and the contents of files the agent has read. This can sometimes lead to confusion or high costs. Use the /compact command to summarize the conversation so far. This frees up space in the context window while keeping the essential information available. If the session becomes too cluttered or the agent starts making repetitive mistakes, you can use /clear to start over in the same folder without losing your configuration files.

To return to a previous task, use "claude --continue" or the -c flag to pick up exactly where you left off in the most recent session. If you need to switch between different tasks within the same project, "claude --resume" or the -r flag gives you a list of earlier sessions to choose from. This history management allows you to maintain multiple threads of context without them bleeding into each other. Each session stays focused on its specific goal while still benefiting from project-wide instructions.

The /memory command allows you to see what the agent has stored about the current session. This is helpful for verifying that it has captured the important details of your request. If the agent is missing context that you previously provided, you can remind it or use the /compact command to refocus its attention. Managing the session life cycle is a key skill for working efficiently with terminal-based agents.

Organizing multiple contexts with adhdTerminal

When you work on several features or different repositories at once, the terminal can become a bottleneck. It is hard to keep track of which session is doing what when you only have one prompt. This is where adhdTerminal helps by letting you run many Claude Code sessions side by side. adhdTerminal is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. Each session lives in its own tile on a wall, which you can name and color-code based on the task.

The wall in adhdTerminal shows you the last few exchanges of each conversation and the current status of the agent. You can see at a glance if a session is working, waiting for you, done or idle. This layout makes it much easier to manage the context of several complex projects simultaneously. Because tiles reopen in the same place after a restart and resume the same session, you never lose the mental map of your work. A free iPhone app mirrors the wall over an end to end encrypted link and can answer a prompt or send the next task.

Using adhdTerminal allows you to separate your backend tasks from your frontend tasks in different tiles. Each tile maintains its own Claude Code session with its own specific history. This prevents the agent from getting confused by unrelated changes in other parts of the repository. It costs 99 dollars once, and one key runs one computer at a time and can be moved. There is a 7 day free trial and no account is required to start organizing your terminal sessions visually.

Extending the agent with custom commands and subagents

You can create specialized context by defining custom slash commands. These are markdown files stored in the .claude/commands directory. Each file defines a new command that the agent can execute. This is useful for complex workflows that you perform often, like generating a specific type of report or running a multi-stage migration. By writing these commands, you give the agent a predefined set of steps to follow, which reduces the chance of errors.

Subagents provide another layer of specialized context. You define them in .claude/agents as markdown files. These files describe a specific role or persona the agent should adopt for certain tasks. For example, you might create an agent that is an expert in your database schema or one that focuses entirely on accessibility audits. When you use the /agents command to trigger one, it operates with the specific instructions and constraints you provided.

Using subagents allows you to delegate parts of your project to assistants that understand their specific domain perfectly. You can have a subagent for security reviews and another for performance optimization. Each one can have its own CLAUDE.md file or specialized settings. This modular approach to context prevents the main agent from becoming overloaded with too many instructions at once, keeping its responses sharp and relevant.

Handling permissions and automation hooks

Context also involves how much control the agent has over your system. You can switch between different permission modes like plan or acceptEdits using Shift+Tab inside a session. In plan mode, the agent only suggests changes without applying them, which is a safe way to explore new ideas. If you trust the agent with a routine task, bypassPermissions allows it to work without asking for your approval at every step. You can also fine-tune these permissions in your settings.json file for specific tools.

To automate context-related tasks, use hook events like SessionStart or PreToolUse. You can configure the agent to perform certain actions every time a session begins, such as checking for updates with "claude update" or running a linter. The Notification hook can alert you when a long-running task is done. These hooks help integrate the agent into your existing developer workflow. By setting up these triggers, you ensure that the agent always has the latest information from your environment.

Finally, you can use the ~/.claude/CLAUDE.md file to set global context that applies to every single project you touch. This is the place for your personal preferences that never change, such as your name, your favorite coding patterns, or the way you like to receive feedback. When combined with project-specific files and subdirectory instructions, these global rules create a comprehensive context system that makes the agent a truly effective partner in your development work.

Questions people ask

How do I stop Claude Code from reading large, irrelevant files?

Claude Code respects .gitignore by default, so ensure your large data files or build artifacts are listed there. You can also use specific instructions in your CLAUDE.md file to tell the agent which directories to avoid. This keeps the context window focused on your source code.

Can I use MCP servers to give the agent more context?

Yes, you can use the "claude mcp" command to manage servers that provide extra data to the agent. These servers are configured in the .mcp.json file. This allows the agent to pull in context from external databases or documentation search tools.

What happens if I have conflicting instructions in different CLAUDE.md files?

The agent generally prioritizes the instructions in the CLAUDE.md file closest to the file it is currently working on. A file in a subdirectory will take precedence over the root file for tasks within that folder. This allows you to set specific local overrides while maintaining global project standards.

Read next

More on claude code basics·All posts