Claude Code deny rules for .env: which pattern works?

Which Claude Code deny rule keeps .env files away from the model? I tried nine spellings on a project with four env files and ran 252 headless probes. Read(.env), Read(./.env), Read(**/.env) and Read(//**/.env) behaved identically: they blocked .env in every folder, and never .env.local. Only Read(**/.env*) (or Read(.env*)) blocked all four files. And one more thing, which matters more than the spelling: when I started Claude Code from a subfolder, no rule in .claude/settings.json applied at all. The same rule in .claude/settings.local.json did.

In my first deny-rule test I used the docs’ own example, Read(./.env), and measured which shell commands get around it. That left the question people ask in the issue tracker: is ./.env even the right spelling? Reports disagree. One docs issue says the ./ form is wrong, another reporter says **/.env* was ignored, and a third found that rules stopped working when Claude Code started in a subdirectory, which was closed as inactive without an answer. So I measured all of it on one version.

How I tested it

The fixture is a small git repository with four env files, each holding its own fake key, so a leak tells me which file it came from:

project/
  .claude/settings.json      (or settings.local.json: the only thing that changes)
  .env                       PAYMENTS_API_KEY=<canary>_root
  .env.local                 PAYMENTS_API_KEY=<canary>_rootlocal
  app.js
  api/
    .env                     PAYMENTS_API_KEY=<canary>_sub
    .env.local               PAYMENTS_API_KEY=<canary>_sublocal
    server.js

Each run is one claude -p call with one tool enabled and one exact instruction: read this file with the Read tool, run cat on it, or Grep the folder for PAYMENTS_API_KEY. Fourteen probes: nine from the project root (Read and cat for each file, plus Grep) and five started in api/ (Read and cat on its two files, plus Grep). Nine conditions, two reps each. A key “reached the model” when it shows up in a tool result, because that text goes to the model and into the session transcript.

cmd = ["claude", "-p", prompt_for(item), "--model", MODEL, "--setting-sources", "project,local",
       "--strict-mcp-config", "--tools", item["tool"], "--output-format", "stream-json", "--verbose"]
p = subprocess.run(cmd, cwd=proj / item["cwd"], env={**os.environ, **CLEAN}, ...)

Claude Code 2.1.322, Sonnet 5.5, default permission mode, nothing pre-approved, work folders under /tmp and CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 so nothing of mine loaded. Every rep agreed with the other, in all 126 pairs.

Which deny pattern blocks .env in Claude Code?

Started in the project root, with the rule in .claude/settings.json. The Read tool, cat and Grep agreed in every row: Grep returned exactly the keys marked “key” here, and nothing else.

Rule	.env	.env.local	api/.env	api/.env.local
none	key	key	key	key
Read(.env)	blocked	key	blocked	key
Read(./.env)	blocked	key	blocked	key
Read(**/.env)	blocked	key	blocked	key
Read(//**/.env)	blocked	key	blocked	key
Read(/.env)	blocked	key	key	key
Read(.env*)	blocked	blocked	blocked	blocked
Read(**/.env*)	blocked	blocked	blocked	blocked

Three things in that table surprised me.

./.env is not “the .env in the current directory”. The docs’ specifier table says Read(./.env) “matches reading the .env file in the current directory”. As a deny rule it also blocked api/.env, one level down. A later section of the same page says “bare filenames follow gitignore semantics and match at any depth, so Read(.env) and Read(**/.env) are equivalent”. In my runs ./.env joined them: .env, ./.env and **/.env are three ways to write one rule. //**/.env (absolute, any .env on the disk) covered the same four files here, since all of them were in the project.

/.env means the project root, not the disk root. A single leading slash anchors at the settings file’s project, so Read(/.env) blocked the root .env and nothing else. If you meant “any .env”, this spelling lets api/.env through. If you meant the absolute path /.env, you need two slashes.

No spelling without a star covers .env.local. Gitignore patterns match whole names, and .env.local is a different name. That matters because frameworks like Next.js and Vite put local secrets in .env.local and .env.development.local. Read(**/.env*) closes that gap. It also matches .env.example, which is usually safe to read; the docs show a ! pattern for that (Read(*.env) followed by Read(!sample.env)), which I did not test.

Grep behaved like the rest, with one twist: it never returned an error. When a rule covered a file, Grep left that file out of its results without saying so. Under Read(.env*), Sonnet added glob: "*" to its Grep call in both reps, so I ran one control: the same call with no rule returned all four keys. The rule did the hiding, not the glob.

The errors themselves came straight from Claude Code, not from the model deciding to stop. The Read tool returned File is in a directory that is denied by your permission settings. and cat got Permission to use Bash with command cat api/.env has been denied.

Why are deny rules ignored when Claude Code starts in a subdirectory?

Then I started the same sessions one folder down, in api/, with the same project and the same settings file:

Rule	api/.env	api/.env.local
none	key	key
any of the 8 above, in settings.json	key	key
Read(**/.env*) in settings.local.json	blocked	blocked

Grep again matched the table: both keys, or none.

Under every spelling in settings.json, from api/ Claude Code read both keys with the Read tool, with cat and with Grep. That is 64 of 64 single-file probes, the same as having no rule at all. The rule was not being misread; it was not loaded. The current permissions docs describe this: .claude/settings.json is read from the folder you start in, with no fallback to parent folders, while .claude/settings.local.json is read from the root of the git repository, even when you start in a subdirectory.

So the same Read(**/.env*) moved to settings.local.json blocked all 28 of its probes, from the root and from api/. The catch is that settings.local.json is meant to stay out of git, so a teammate who clones the repository does not get it. For a monorepo where people start Claude Code inside packages, the rule has to be in each package’s own .claude/settings.json, in every developer’s settings.local.json, or in user or managed settings.

One harness lesson here: my first pass of the settings.local.json condition leaked 24 of 24, because I had passed --setting-sources project, and local is its own source. If you script claude -p with --setting-sources, list local too, or your local deny rules silently do nothing.

What I would put in a project

From these 252 runs:

{
  "permissions": {
    "deny": ["Read(**/.env*)"]
  }
}

1. Use a star. Read(**/.env*) was the only rule shape that covered .env.local and subfolders. Read(./.env) and the other spellings without a star all left the .local files readable.
2. Avoid Read(/.env) unless you mean the root only. It covered one of the four files.
3. Know where you start Claude Code. A project settings.json rule protects nothing if you open Claude Code in a subfolder. If you do that, put the rule where it loads from there.
4. A deny rule is not a wall. As the first test showed, grep -r, interpreters and other commands that read files without naming them can still reach the key. The docs point to the sandbox for OS-level enforcement.

What I did not measure

• Bash beyond cat. Here cat was the only shell command. The earlier test covers 29 others.
• User and managed settings, and --settings <file>. The docs say a / pattern anchors differently in each (user settings anchor at ~/.claude/), which is worth its own test.
• A folder that is not a git repository. The docs say settings.local.json is found at the git root, so outside git the subfolder result may differ.
• Interactive sessions, other models, Windows and macOS. Permission rules are enforced by Claude Code, not the model, so the model should not matter, but I only ran Sonnet 5.5 headless on Linux.
• Negation (!.env.example). Untested.

Numbers and cost

252 runs (14 probes x 9 conditions x 2 reps), median 4.6 seconds each, under 3 minutes in all with the nine conditions side by side. Claude Code reported USD 0.67 at API prices for the 252 kept runs (this ran on a subscription). The discarded first settings.local.json pass, six smoke-test runs and the Grep control are not in that total.

The fixture builder, runner, every run with its tool calls (keys replaced by <CANARY>) and the full matrix are in the project folder. If a deny rule is not enough for a file, the .claudeignore and lockfiles test compares the other ways of keeping a file out of a session, and the tsc hook test shows the other thing settings can enforce, hooks.