On this page
Claude Code can read project files it has permission to access. That's what makes it useful, and it's also the risk: one "show me the config" and the API keys in your .env file can end up in the chat log.
I ran into this while making a course on vetting Claude Code plugins. The more plugins and hooks I reviewed, the clearer it became: an AI agent reading secrets it never needed is one of the easiest mistakes to make, and one of the hardest to undo.
What env-guard does
env-guard adds a PreToolUse hook to Claude Code. Before Claude reads a file, runs a shell command or searches files, the hook checks whether the request mentions a .env file. If it does, the action is blocked and Claude is told why. Templates like .env.example, .env.sample and .env.template still work.
Since version 0.2.0, the same hook also blocks mobile signing keys: Android keystores (*.jks, *.keystore), key.properties (keystore passwords), iOS signing certificates (*.p12) and App Store Connect API keys (*.p8).
It also adds a /env-guard:env-check skill that lists any .env files tracked by git and shows how to untrack them.
The bug that taught me the most
The first version only watched Read and Bash. Then I realised a simple Grep for "API_KEY" could print the value straight into the chat without ever opening the file. Version 0.1.5 added Grep, checking both its path and glob, with tests for each case.
The lesson for anyone building guard plugins: list every tool that can read a file, not just the obvious one.
What it never does
No network access, nothing is sent anywhere. It never reads, logs or stores your .env contents, never changes settings.json or your permissions, and downloads nothing.
Honest limits
It's a guardrail against accidents, not a security boundary. It watches only Read, Bash and Grep. Grep checks the path and glob, so a search across a whole folder can still include .env files. If jq is missing, the hook warns and does not block access. A cleverly encoded command can get around it, files you attach yourself with @ aren't checked, and any Bash command that mentions ".env" is blocked, including when it only prints the text with echo. While making the cover image for this launch, env-guard blocked my own command for exactly that reason.
Try it
Works with Claude Code and needs jq. Install it with:
/plugin install env-guard --marketplace yannigoyal/env-guard
To test it safely, create a dummy .env file with fake values. Ask Claude Code to read it and confirm the request is blocked; don't use a real secrets file. Run /env-guard:env-check to see if any .env file is tracked in git.
You can find env-guard in the Awesome AI Plugins registry: https://hol.org/registry/plugins/yannigoyal%2Fenv-guard. The source lives at https://github.com/yannigoyal/env-guard (MIT).
I'd love feedback, especially commands it blocks that it shouldn't, and tools or MCP servers it should watch next.
Want to go deeper? In my course Claude Code Plugins: Vet, Install & Build Them Safely, I show how to check any plugin before installing it, and how I built and tested env-guard step by step: https://www.udemy.com/course/claude-code-plugins-choose-vet-install-safely/?referralCode=FA4ADFBED22777044E8A
