Claude Code and your .env file: how to keep secrets away from the agent
Yes, Claude Code can read the .env file in your project without asking. In manual mode, file reads inside the working directory need no approval. In auto mode, reading .env and sending credentials to their matching API is allowed by default. A deny rule such as Read(./.env) stops that for the file tools and for Bash commands Claude Code recognizes, such as cat. It does not cover a command that reads files without naming them, like grep -r pattern .. Use it as a guard against honest mistakes, not as a wall against an agent that was tricked.
A Claude Code env file is an ordinary .env file. The difference is that the agent works in the same folder. So the question is not only whether the file is in Git, but whether the tool that runs your commands can read it. This page answers that second question.
01What Claude Code can do with your .env file
Claude Code has permission modes that decide what it may do without asking. In manual mode (the config value is default) it asks before Bash commands, except a built-in set of read-only ones. File reads are different: reading and searching inside the working directory needs no approval.
Since Claude Code v2.1.283, interactive terminal and VS Code sessions start in auto mode. In auto mode, reading .env and sending credentials to their matching API is allowed by default.
So in both modes a plain .env in the project root is within reach. The next section closes the easy routes.
02Protect a Claude Code env file with deny rules
A permission rule is one line with a tool name and a pattern in brackets. A deny rule makes Claude Code refuse the matching action. Read(./.env) matches reading the .env file in the current directory. For edits, add an Edit deny rule per path under permissions.deny in .claude/settings.json; Edit(/.env) is the form for the .env at the project root.
Put both rules in .claude/settings.json in the project:
{
"permissions": {
"deny": [
"Read(./.env)",
"Edit(/.env)"
]
}
}Add a line for every .env file name you keep, because the usual setup is one .env file per environment.
Read and Edit deny rules apply to Claude's built-in file tools. They also apply to the Bash file commands Claude Code recognizes (cat, head, tail, sed and tee) and to the targets of redirections such as > file and < file. So yes, Read(./.env) stops cat .env.
03Two ways to write the path
The two rules above look different on purpose. A path written as ./.env is relative to the current directory. A path that starts with a single slash, like /.env, is relative to the settings source, and in project settings that is the primary working directory: the folder where you launched Claude Code, until you move the session with /cd. The slash does not mean the root of your disk.
When the current directory is the primary working directory, both forms name the same file. The slash form stays tied to that folder; the ./ form follows the current directory.
Two details change what a rule catches. A bare file name follows gitignore rules and matches at any depth, so Read(.env) blocks any .env at or under the current directory. And in user settings a single slash points into ~/.claude/: Read(/secrets/**) there blocks ~/.claude/secrets/**, not a folder in your project. For a rule in user settings that covers every project, use a // absolute path or a ~/ path.
04What a deny rule does not cover
A deny rule filters the tool calls and commands that Claude Code recognizes as reading or editing a file. Four gaps matter here.
- Commands that read without naming the file. A deny rule does not apply to a command such as
grep -r pattern .run from the directory that holds the file. That command reads every file in the folder, including.env, and the rule never sees the name. - Scripts that open files themselves. A deny rule does not apply to a subprocess that reads files indirectly, like a Python or Node script that opens the file on its own.
- Rules written for programs. A deny rule on a program name does not match the same program started by its path or inside
sh -c. That is one reason to guard the file itself with aReadrule rather than try to bancatby name. - Other copies of the secret. A key that is also in your shell profile, or exported into the environment, is not protected by a rule on
.env.
A prompt-injected agent, one that follows instructions hidden in a web page or a file, may try routes the rule does not recognize. A hook is a script of your own that Claude Code runs before a tool call. The example hook protect-files.sh refuses edits to .env, and a deny from a PreToolUse hook holds even with --dangerously-skip-permissions. The full script, ready to copy, is on the hooks page.
05Which settings file wins
You can put the same deny rule in more than one place:
| Where | What it does |
|---|---|
| User settings | Apply to all your projects on the Mac. A user-level deny blocks a project-level allow |
Project settings, .claude/settings.json | Apply to this project. If user settings allow something and project settings deny it, the deny wins |
| Managed settings | Highest level. No other level, including command line arguments, can override a managed permission rule |
Rules are checked deny first, then ask, then allow, and the first match wins. An allow rule cannot carve an exception out of a deny rule. The full syntax is on the permissions page.
06What the sandbox does for your .env
A sandbox is a boundary the operating system enforces around the shell commands Claude runs. On macOS it uses the built-in Seatbelt framework. The default does not hide your .env: commands get read access to the entire computer except certain denied directories, and that still allows reading credential files. The sandbox also passes on the environment of Claude Code to commands, including any secrets in it. The sandbox reduces risk but is not a complete isolation boundary. Its limits are on the sandbox page.
07Keep the secret out of the file
The strongest fix is a file with nothing worth reading. Environment variables keep config out of the code, and there is little chance of them being checked into the code repo accidentally. The file itself is still plain text on disk. Passing keys through environment variables or a secrets manager keeps them out of code. One example is 1Password's op run, which loads secrets as environment variables without plaintext .env files. Processes on your computer can still read the environment of other processes run by the same user, so this narrows the exposure and does not remove it.
Malware knows where keys live. The s1ngularity payload searched for wallets, keystores, .env files and SSH keys on Linux and macOS. How it used the agent flags is on the skip-permissions page. For where to put keys on a Mac, see where to store API keys.
To see what actually starts on your Mac while an agent works, the free, open-source core of Artificial Immunity watches program starts and reports what it finds.
08If the agent already read it, or you pushed it
Consider any leaked secret immediately compromised. If it was pushed to a public repository, speed matters: automated scanners can locate publicly exposed secrets in minutes, and malicious actors can exploit them within hours. The most important step is revoking it with its provider. Then look for logs that show the key being used. The order of steps is on the page about a leaked key. The repository side is on a key exposed on GitHub. The lines that keep .env out of Git are on the page about the .env file itself.
09The short version
Your Claude Code env file is safest when three things agree. A Read and an Edit deny rule guard the file, with the known gaps that a command like grep -r or a script that opens the file itself can still reach it. As little as possible sits in the file. And any key that has left your machine is revoked.
FAQ
Does Claude Code read my .env file?
It can. In manual mode, file reads inside the working directory need no approval. In auto mode, reading .env and sending credentials to their matching API is allowed by default. A deny rule changes that.
How do I stop Claude Code from reading .env?
Add Read(./.env) as a deny rule under permissions.deny in .claude/settings.json. Deny rules block in every mode, including bypassPermissions.
Does Read(./.env) stop cat .env?
Yes. Read and Edit deny rules also apply to Bash file commands Claude Code recognizes, such as cat, head, tail, sed and tee, and to redirections. They do not apply to a command that reads files without naming them, such as grep -r pattern . run from the folder that holds the file.
What is the difference between ./.env and /.env in a rule?
./.env is relative to the current directory. /.env is relative to the settings source, which in project settings is the primary working directory.
Is using a .env file safe?
It is common, and variables are unlikely to be checked into the repo by accident. But the file is plain text on disk, and malware searches for it. Keep it out of Git, and out of reach of the agent.
Where should I keep a .env file?
In the root of the project, and never committed. The page about where to store keys compares it with the Keychain and secrets managers.
What happens if we push a .env file?
Treat every secret in it as compromised and revoke the keys first. The steps are on the page about a leaked key.