Last updated 13 October 2026
Manage project environment info in CLAUDE.md
Claude Code needs clear environment context to work
You run claude in a new repository and ask it to fix a bug. The agent uses the Read and Glob tools to understand the code. It then tries to run the tests using the Bash tool. The tests fail immediately because a required environment variable is missing. The agent does not know if it should create a .env file, use an export command, or look for a configuration script. It spends your tokens guessing or asking you for help. This delay breaks your flow and wastes money.
The agent starts a session by reading the file structure. It uses the Glob tool to find relevant files. If it sees a package.json file, it assumes it should use npm or yarn. However, it does not know which one you prefer unless you tell it. Without environment info in CLAUDE.md, the agent might run a command that modifies your lockfile in a way you do not want. It might also try to use a global tool that is not in your path. This results in a series of bash errors that you have to manually fix. You end up teaching the agent the same setup steps every time you start a new session.
The CLAUDE.md file acts as project memory
CLAUDE.md is the solution to this repetition. It acts as a persistent memory for the agent across different sessions. When you run the claude command, the agent immediately consumes the contents of this file. You should define the project name, the primary language, and the specific build tools you use. If you have a specific way of running the development server, write it down. For example, tell the agent to always use a specific port or to include certain flags. This ensures that every time the agent uses the Bash tool, it does so with the correct context.
Treat CLAUDE.md as the primary source of truth for the agent. Place it in the root of your repository to ensure it is always accessible. The agent uses the Read tool to parse this file at the start of every session. If you provide clear instructions on how to handle the project environment, the agent will spend less time asking for clarification. This file is not just for environment variables. You should also include style guides, architectural patterns, and testing protocols. By centralizing this information, you create a more efficient workflow for every task the agent performs.
Documenting environment variables prevents runtime errors
Environment variables are often the biggest hurdle for an AI agent. It cannot see your local environment variables unless it runs a bash command to check them. Instead of letting it guess, list the required variables in your CLAUDE.md file. Use a section dedicated to Environment Setup. Explicitly state which variables are needed for the backend and which are for the frontend. If the agent needs to fetch a value from a secret manager, give it the exact command to run. This prevents the agent from stalling when it encounters a missing configuration value during execution.
Do not put actual secrets like API keys in CLAUDE.md. Instead, list the required keys and explain where the agent can find a template. For example, tell the agent to look for a .env.example file. Instruct it to copy this file to .env using the Bash tool and then ask you to fill in the missing values. If the agent knows that certain variables are required for the build to pass, it will check for them before it attempts to run the code. This prevents a loop of failing builds and keeps your token usage low.
Define build and test commands for consistent execution
You should also specify how to handle local configuration files. Many developers use a .env file that is ignored by git. Tell the agent to use the Read tool to check for the existence of this file. If the file is missing, instruct the agent to use the Write tool to create it from a template. You can even provide the exact values for non-sensitive variables directly in CLAUDE.md. This allows the agent to set up its own working environment without your constant intervention. It makes the agent much more autonomous and useful for complex tasks.
Claude Code is good at guessing common commands like npm test or pytest. However, many projects use custom flags or specific environment wrappers. Write the exact bash commands in CLAUDE.md. Tell the agent to use a specific test runner or a specific port for the local server. If your project requires a specific version of a runtime, state that clearly. The agent can then use the Bash tool to check the version before it starts working. This saves time during the initial setup of a session and ensures that the agent does not use deprecated commands.
Infrastructure requirements belong in your project instructions
Testing infrastructure often requires specific setups. If your tests need a database, tell the agent how to start it. You might use a bash command to run a docker container or a script that sets up a temporary sqlite database. Specify these steps in CLAUDE.md so the agent can prepare the environment before running tests. If the agent uses the Task tool to track its progress, it can mark the environment setup as the first completed step. This provides you with a clear view of what the agent has done and what it is currently working on.
If your project depends on a local Redis instance or a complex microservice stack, document this in CLAUDE.md. The agent cannot see what is running on your system without using the Bash tool. Tell it which commands to run to verify that the necessary services are active. You can provide a command that checks for a running container or a specific listening port. If the service is missing, the agent can inform you instead of failing with a generic connection refused error. This makes the interaction much more predictable and professional.
Visualizing multiple sessions with adhdTerminal tiles
When you manage multiple projects, keeping track of different environment requirements becomes difficult. adhdTerminal simplifies this by letting you run many Claude Code sessions side by side. Each session is a tile on a wall with its own name and color. You can have one tile for a frontend project and another for a backend service. Each tile shows the last exchanges of the conversation and the status of the current task. If a tile shows an error, you can quickly see if it is an environment issue. This visual organization helps you manage complex local environments without losing your focus.
Each tile in adhdTerminal shows whether the agent is working, waiting for you, done or idle. You can see the last exchanges of its conversation at a glance. This is particularly useful when you are setting up environments across a microservices architecture. You do not have to cycle through terminal tabs to check if a service has successfully connected to its database. The wall of tiles gives you a high-level view of your entire development stack. You can quickly identify which session needs your attention and which one is successfully running its environment checks.
Use subdirectory instructions for complex repositories
Use the hierarchical nature of CLAUDE.md to your advantage. A CLAUDE.md file in the root of your repository should contain general instructions for the whole project. If you have a subdirectory for a specific service, place another CLAUDE.md file there. This file should contain requirements specific to that service. The agent will read both files when it works in that subdirectory. You can also use a global CLAUDE.md file in your home directory at ~/.claude/CLAUDE.md. This is the place for your personal preferences, such as your favorite editor or common bash aliases you want the agent to use.
This tiered approach allows you to manage environment variables more effectively. You can keep the root instructions clean while providing deep context for specific components. For example, a backend folder might require specific database environment variables while the frontend folder requires a specific node version. The agent combines these instructions to form a complete picture of the environment. This hierarchy keeps the instructions clean and relevant to the current task. It prevents the agent from becoming overwhelmed by irrelevant information from other parts of the project.
Maintain your project instructions through active sessions
Maintaining the quality of your instructions is a continuous process. Use the /memory command inside a session to see what the agent has learned about your environment. If the agent is confused or has stored incorrect information, you can correct it. Use the /compact command to clean up the session context while keeping the important instructions. You can also use the /status command to check the current state of the agent and its permissions. If you find yourself giving the same instruction multiple times, it is time to move that instruction into the CLAUDE.md file.
You can even ask the agent to help you write the environment documentation. Since it has access to the Edit and Write tools, it can update CLAUDE.md based on the errors it encountered during the session. This creates a feedback loop where the agent documents its own environment requirements. You can review these changes before they are committed. This practice ensures that your project documentation stays up to date with the actual runtime requirements. It makes the onboarding process for the agent much smoother in future sessions.
Remote monitoring keeps environment setups moving
Use the .claude/settings.json file for project-wide settings and .claude/settings.local.json for your own overrides. These files complement the instructions in CLAUDE.md. You can define permission modes like acceptEdits or plan to control how the agent interacts with your environment. If you want to prevent the agent from ever modifying certain configuration files, you can set these permissions in the settings. This adds a layer of safety when the agent is experimenting with environment setups. You can also use the /config command to view or modify these settings during a session.
Monitoring your sessions from another device can be helpful during long environment setups. The adhdTerminal iPhone app allows you to see your wall of tiles from anywhere. The link is end to end encrypted for your security. If the agent finishes a build or needs a permission to run a tool, you can handle it from your phone. You can use the iPhone app to send the next task or answer a prompt. This flexibility allows you to keep your development environment moving forward while you take a break or move between workstations.
Questions people ask
How do I hide my real API keys from Claude Code?
Never put raw secrets in CLAUDE.md or any file the agent can read. Instead, list the variable names and point the agent to a template file like .env.example. The agent can use the Read tool to see what is required and then ask you to provide the values manually.
Can I use separate instructions for different parts of a monorepo?
Yes, you can place a CLAUDE.md file in the root directory and separate CLAUDE.md files in each subdirectory. The agent reads the instructions from the root and then adds the instructions from the subdirectory it is currently working in. This allows you to define different environment requirements for your frontend and backend services.
What happens if the agent ignores the CLAUDE.md file?
If the agent is not following your instructions, use the /memory command to check what it has currently stored. You may need to use the /compact command to refresh its context or explicitly tell it to re-read the CLAUDE.md file. Ensuring your instructions are clear and at the top of the file also helps the agent prioritize them.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.