Last updated 13 October 2026
Pass environment variables to Claude Code
Claude Code inherits the shell environment
When you run the claude command, the agent starts as a process within your current shell. It sees the same environment variables that your shell sees at that moment. If you have an API key or a database URL exported in your terminal session, the agent can access them when it runs the Bash tool to execute your tests or build scripts. This is the most direct way to pass secrets and configuration to the agent without writing them to disk.
Problems arise when you expect the agent to know about variables defined in a configuration file that you have not sourced. If your build depends on a specific path or a token, you must ensure your terminal session has that variable set before you type claude. The agent cannot automatically guess which shell profile or environment file it should load unless you explicitly tell it to do so or provide those variables beforehand.
Managing persistent project instructions
The CLAUDE.md file in your repository root serves as the primary manual for the agent. You should use this file to document which environment variables are necessary for the project to function. While you should never put actual secrets like production passwords in CLAUDE.md, you can list the names of the required variables. This helps the agent understand why a build might be failing and allows it to ask you for the missing information or look for it in the right places.
You can also place a CLAUDE.md file in a subdirectory if that specific part of your project requires different environment settings. For example, a frontend folder might need specific build flags while the backend needs database credentials. The agent reads the project instructions from the root and then applies the more specific instructions from the subdirectory when it works in that part of the tree. This hierarchy ensures that the agent always has the correct context for the task at hand.
Using local settings for user overrides
If you have personal configurations that should not be shared with the rest of your team, use the .claude/settings.local.json file. This file is intended for your own untracked overrides. It is a good place to define how the agent should behave on your specific machine. You can use this file to set permissions or configure how the agent interacts with your local environment. This file stays on your machine and does not get committed to the repository, keeping your local preferences private.
The agent also looks at the global configuration in ~/.claude/settings.json for settings that apply to every project you work on. If you have a specific way you like to handle environment variables across all your development work, you can define those preferences there. By separating project-wide instructions in CLAUDE.md from your personal preferences in the local settings files, you create a configuration that is both collaborative and customized.
Executing commands with the Bash tool
The agent frequently uses the Bash tool to run commands, check the state of your project, or execute scripts. When it does this, it is operating within the environment of the session. If you need to pass a temporary environment variable for a single command, the agent can do this by prefixing the command with the variable assignment. This is useful for one-off tasks where you do not want to change the global environment of your shell.
Because the agent has access to the Bash tool, it can also source files like environment configuration files if you instruct it to. If your project uses a standard environment file, you should mention this in your CLAUDE.md file. The agent can then use the Read tool to see the names of the variables it needs and then use the Bash tool to ensure those variables are present before running a build or a test suite. This mimics the exact workflow a human developer follows when setting up a local development environment.
Handling secrets and sensitive data safely
Security is a major concern when using any coding agent. You must be careful not to expose sensitive credentials to the conversation history if you do not want them included in the context window. Claude Code respects your .gitignore file, so it will not automatically read files that you have excluded from your repository. This is an important safety feature that prevents the agent from accidentally reading and uploading your secret keys or private configuration files unless you explicitly tell it to do so.
When you need the agent to use a secret, it is better to have the secret already present in the shell environment. This way, the Bash tool can use the secret without the agent ever needing to see the value in plain text within the chat interface. If the agent needs to write a configuration file, it can use the Write tool or the Edit tool to create a template, and then you can fill in the actual secrets manually. This keeps your most sensitive data out of the agent memory and out of any logs.
Multiplexing sessions with different environments
When working on complex systems, you might need to run multiple Claude Code sessions at the same time, each with a different set of environment variables. For instance, you might have one session focused on a staging environment and another on the local development environment. Switching back and forth in a single terminal window is slow and error-prone. This is where adhdTerminal becomes useful. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic.
The app runs many Claude Code sessions side by side, each one a tile on a wall. A tile has a colour, a number and a name, and shows whether it is working, waiting for you, done or idle. Tiles reopen in the same place after a restart and resume the same session. A free iPhone app mirrors the wall over an end to end encrypted link and can answer a prompt or send the next task. It costs 99 dollars once, one key runs one computer at a time and can be moved, with a 7 day free trial and no account. This setup helps you track different environment states at a glance while keeping your secret keys and local configs separate.
Validating the environment with doctor and status
If you suspect that the agent does not have access to the variables it needs, you can use the /doctor command or run claude doctor from your shell. These commands check the health of your installation and can help identify issues with your configuration. While these tools are designed to check the software itself, the output often provides clues about whether the agent can correctly interact with your system and its environment.
You can also use the /status command inside a session to see information about the current state of the agent. This includes the current permission mode and any active MCP servers. If your environment variables are meant to configure an MCP server, you should check your .mcp.json file to ensure the configuration is correct. The agent uses these servers to extend its capabilities, and they often require their own environment settings to communicate with external APIs or databases.
Controlling permissions for environment access
Claude Code has different permission modes that change how much it can do without asking you. You can cycle through these modes by pressing Shift+Tab. In the bypassPermissions mode, the agent can run tools and edit files without asking for your approval every time. This can be faster when you are doing repetitive work that requires setting many environment variables or running many shell commands. However, you should use this mode with caution, especially when the agent has access to sensitive environments.
If you want to restrict what the agent can do with specific tools, you can modify the permissions section in your .claude/settings.json file. You can allow or deny specific tools globally or on a per-project basis. This gives you fine-grained control over how the agent interacts with your shell and your environment. By setting these permissions correctly, you can ensure that the agent only accesses the variables and files that are necessary for its current task, providing an extra layer of security for your development workflow.
Questions people ask
How can I see which environment variables the agent currently sees?
You can ask the agent to run a command to print environment variables using its Bash tool. This will display all variables currently exported in the shell session where Claude Code is running. Keep in mind that this will put those values into the conversation history and the context window.
Can I set an environment variable that persists across different Claude Code sessions?
To make a variable persist, you should add it to your shell profile or use a dedicated environment file that you source before starting the agent. You can also mention the variable name in your CLAUDE.md file so the agent knows to look for it or set it using the Bash tool in every new session.
Does Claude Code automatically load my bashrc or zshrc file?
The agent runs in the environment of the shell that launched it, so it inherits whatever that shell has already loaded. It does not typically re-source your configuration files when it runs the Bash tool. If you have specific aliases or functions in your shell profile, you may need to tell the agent to source those files explicitly if it needs them for a task.
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.