Let a coding agent check your project for API keys without seeing them
By Flavio
Have a coding agent find hardcoded keys, .env values and old commits with secretsfree, using redacted JSON, so the keys never land in its context.
You asked a coding agent to wire up email, and it pasted the Resend key straight into src/email.ts. Now you want it to check the rest of the project for the same mistake. The obvious way is to let it grep for sk_ and re_, open .env, and read the history. Every one of those prints the full key into its context, which goes to the model provider and into the session log.
Secrets Free has a command, secretsfree, that does the looking for the agent. It reads the files, the ignored files and the history on your Mac, and prints each finding with the key masked. The agent gets a path, a line, a rule and a fingerprint. It doesn’t get the value.
By the end you’ll have the command on the agent’s path, a short block of rules in your AGENTS.md, and a loop where the agent finds keys, moves them out of the code, and asks you before it accepts any as safe.
What you need
Secrets Free runs on macOS 14 or later, on Apple silicon and Intel Macs. Your Polar receipt has two downloads: Secrets-Free-1.1.0.zip with the Mac app, and Secrets-Free-1.1.0-source.zip with the full MIT-licensed source. The receipt always has the latest version of both.
The secretsfree command isn’t inside the app bundle. You build it from the source zip, which needs Xcode 26 or a Swift 6.2 toolchain. Check yours before you start:
swift --version
It should report Swift 6.2 or later. Git needs to be on your PATH too, because the scan uses it to tell tracked files from ignored ones and to read the history.
Any coding agent that runs shell commands works here: Claude Code, Codex, Cursor and others. The agent needs nothing special. It runs one command and reads its output, like a test runner.
Everything stays on your Mac. The scan reads local folders only, never clones a remote, and uploads nothing. The app’s daily update check sends the license key and the app version, never anything from your files.
In the examples, recipe-box is an example project with random fake keys I generated for this page, and the paths are examples too.
Install the command where the agent can find it
An agent doesn’t run commands in your terminal. It starts its own shell, often non-interactive, and that shell may not read the config file where you added a folder to your PATH. So the command that works when you type it can be missing for the agent. That’s the most common reason this setup fails on the first try, and the agent will usually react by trying something else, like grepping for keys itself. Installing to a known folder and using the full path in your instructions avoids the guesswork.
From the unzipped source folder, run the installer:
./Scripts/install-cli.sh
It builds the release binary and links it into ~/.local/bin. Pass another folder to link it there, like ./Scripts/install-cli.sh /opt/homebrew/bin. When the folder isn’t on your PATH, the script says so:
Installed /Users/flavio/.local/bin/secretsfree -> /Users/flavio/apps/secrets-free/.build/release/secretsfree
Note: /Users/flavio/.local/bin is not in your PATH. Add it to your shell config.
The link points into the source folder’s .build, so keep that folder where it is. Check that the command answers:
~/.local/bin/secretsfree version
1.1.0
Run the installer again after you download a new source zip, and it rebuilds and replaces the link. To remove the command, delete the secretsfree link from ~/.local/bin.
Write the rules into AGENTS.md
Agents follow what’s written in their instruction file far more reliably than what you tell them once in a chat. The rules here cover the three ways a key ends up in the agent’s context anyway: it opens .env, it passes --reveal, or it decides on its own that a finding is safe and hides it. Each rule closes one of those. If you’re new to the file, What is an AGENTS.md file explains where agents look for it. Claude Code reads CLAUDE.md, so put the same block there or point one file at the other.
Add this to AGENTS.md at the project root:
## Secrets
- Never open, cat or grep `.env`, `.dev.vars` or any credentials file.
- To look for secrets, run `~/.local/bin/secretsfree scan --json --fail-on never`.
Add `--include-ignored` to cover `.env` files and `--history` for old commits.
- Never pass `--reveal`.
- For a key in code, replace the value with an environment variable read
without printing the line, and tell me the variable name.
- Never run `secretsfree ignore` yourself. List the fingerprints you think
are safe, with the reason, and wait for me.
The --fail-on never part matters for agents. Without it, scan exits with status 1 whenever it finds something at high or above. Many agents read a non-zero exit as “the command broke” and start debugging the scanner. With never, exit 0 means the scan ran, and the findings are in the JSON.
Here’s the loop those rules set up:
Let the agent scan without the values
This is the step that replaces “grep the project for keys”. The scan reads every file a push would publish, which inside a Git repo means tracked and untracked files but not ignored ones. It runs each line through 69 rules, from Stripe and OpenAI keys to database URLs with passwords. What comes back is masked: the first four and last two characters of each value, with the middle hidden. Values of 10 characters or fewer are hidden entirely. The agent can still tell a Stripe live key from a test key by its prefix, which is all it needs to decide what to do.
Example 1: the agent checks the project it just changed. In recipe-box, the agent runs the command from its rules:
~/.local/bin/secretsfree scan --json --fail-on never
Here’s one finding from the output, the Resend key it pasted earlier:
{
"context" : "const resend = new Resend(\"re_O••••••••••••••••••dS\");",
"entropy" : 4.66992500144231,
"fingerprint" : "234b978c1565",
"line" : 2,
"location" : {
"workingTree" : {
}
},
"path" : "src\/email.ts",
"redacted" : "re_O••••••••••••••••••dS",
"ruleID" : "resend-api-key",
"ruleName" : "Resend API key",
"secret" : "re_O••••••••••••••••••dS",
"severity" : "critical"
}
The secret field is masked too. It only holds the full value when --reveal is passed, which is why the rules forbid it. The context line is the source line with the secret masked inside it, so the agent knows what code to change without seeing the key.
The rest of the report wraps the findings with the target, the options, the file and commit counts, and any warnings. With --json, nothing else goes to standard output, so the agent can parse it directly. The same scan found a Stripe test key in a fixture and the sender address in src/email.ts, which the identity rules flag as low. Add --no-identity if you only care about credentials.
For a quick read, the agent can trim the JSON to one line per finding with jq:
~/.local/bin/secretsfree scan --json --fail-on never \
| jq -r '.findings[] | "\(.severity) \(.ruleID) \(.path):\(.line // "-") #\(.fingerprint)"'
critical resend-api-key src/email.ts:2 #234b978c1565
medium stripe-test-key test/fixtures/checkout.json:1 #73ef280c0960
low email-address src/email.ts:4 #3157c2e2845d
Running it a second time gives the same fingerprints. Each one is the first 12 hex characters of a SHA-256 over the rule ID, the file path and the secret. Moving the line doesn’t change it, but renaming the file does.
Cover .env files and old commits
The default scan skips what Git ignores, because that’s what a push would publish. But the files the agent must not open are exactly the ignored ones: .env, .dev.vars, credentials files. And the history holds keys you removed months ago, which the agent would only see by reading old diffs. --include-ignored and --history let the scanner read both on the agent’s behalf. The agent learns that .env holds a Stripe live key on line 1 without the key ever reaching it.
Example 2: the same project with ignored files and history. The agent adds both flags:
~/.local/bin/secretsfree scan --history --include-ignored --json --fail-on never \
| jq -r '.findings[] | "\(.severity) \(.ruleID) \(.path):\(.line // "-") #\(.fingerprint)"'
critical file-dotenv .env:- #867ca56c343e
critical stripe-secret-key .env:1 #325537ff29ab
critical openai-api-key .env:2 #0dadf6c9d54b
critical openai-api-key src/ai.ts:2 #1e865b57a17a
critical resend-api-key src/email.ts:2 #234b978c1565
medium stripe-test-key test/fixtures/checkout.json:1 #73ef280c0960
low email-address src/email.ts:4 #3157c2e2845d
Four new findings. The .env file is flagged by its name, and the two keys in it by their rules. That’s expected: .env is where keys belong, as long as Git ignores it. The interesting one is src/ai.ts:2. Today’s file reads the OpenAI key from the environment, so this key only exists in an old commit. In the JSON, its location says so:
{
"history": {
"author": "Flavio",
"commit": "e89dc3fc2279e07dd9a5ece0827c59f104f9fb56",
"date": "2026-10-12T10:00:00+02:00"
}
}
No edit fixes a key in history. When the text scan finds one, it ends with this line:
1 finding exist only in git history. Rotating the secret is the fix; rewriting history alone does not un-leak it.
So the agent’s job here is to tell you which provider and which commit. Rotating the key at the provider is yours. Checking old commits before a push, and blocking a push with a hook, are covered in Scan your Git history for leaked API keys before you push.
--include-ignored also reads heavy folders like node_modules. Keep it for a full audit, not for every scan.
Move a hardcoded key out without printing it
The usual fix for a key in code is to read it from an environment variable. An agent would normally open the file, look at the line and rewrite it, which puts the key in its context. Since the scan already gave the path, the line number and the masked context, the agent can change the line without displaying it. Then you put the real value in .env yourself. This keeps the key out of the transcript from here on. If the agent opened the file earlier in the session, it has already seen the key, and that’s worth a rotation if the key matters.
For src/email.ts:2, the agent replaces whatever sits between the quotes, by line number, and prints only the result:
sed -i '' '2s/new Resend("[^"]*")/new Resend(process.env.RESEND_API_KEY)/' src/email.ts
sed -n 2p src/email.ts
const resend = new Resend(process.env.RESEND_API_KEY);
The sed pattern never contains the key, so neither the command nor its output shows it. The agent then tells you the variable name, and you add RESEND_API_KEY= with the value to .env in your editor. Check that .gitignore lists .env before you do.
To undo the edit, git checkout -- src/email.ts brings the file back. That also brings back the key in the code, so only do it before you commit.
Accept a fixture by fingerprint
Some findings are fine. A test fixture with a Stripe test key, an example in a README, a fake token in a mock. If they stay in the list, every scan reports them, and the agent wastes time on them or, worse, learns to skip critical findings. The allowlist removes them by fingerprint. Since the fingerprint covers the value, a different key added to the same file later still shows up. That’s why the decision should be yours: an agent that hides findings to get a clean scan would be doing exactly the wrong thing.
The agent lists 73ef280c0960 in test/fixtures/checkout.json as a Stripe test-mode key in a fixture. You agree, so you run:
secretsfree ignore 73ef280c0960
Added fingerprint 73ef280c0960 to /Users/flavio/dev/recipe-box/.secretsfree.json
The fingerprint goes into .secretsfree.json at the scan root. Commit that file, so every clone and every agent skips the same reviewed findings. Running the same ignore again doesn’t add a duplicate. To undo, delete the fingerprint from the file.
With the Resend key moved and the fixture accepted, the default scan is clean:
~/.local/bin/secretsfree scan --no-identity
Secrets Free · ~/dev/recipe-box
✓ No findings. 0 findings · 4 files, 1 allowlisted · 0.1s
It exits with status 0. That’s the line to ask the agent for before it says it’s done.
Example 3: the agent points the scan at the wrong folder. The agent was working in a sibling folder and passed a path with a typo:
~/.local/bin/secretsfree scan ~/dev/recipe-bx --json --fail-on never
secretsfree: /Users/flavio/dev/recipe-bx is not a folder.
Standard output is empty, the message goes to standard error, and the exit status is 3. That’s the reason --fail-on never doesn’t hide real failures: 0 is a scan that ran, 3 is a scan that didn’t. An agent that only parses standard output sees nothing and may report “no findings”. Add a line to your rules telling it to check the exit code first, and to treat anything other than 0 as a failed scan.
How to protect secrets when coding agents deploy your app goes further, into what an agent can reach during a deploy. This page keeps to the local check.
If something looks wrong
- If the agent gets
zsh:1: command not found: secretsfree(exit status127), its shell doesn’t have~/.local/binon thePATH. Use the full path~/.local/bin/secretsfreeinAGENTS.md. - If the agent says the scan failed while the JSON has findings, it ran without
--fail-on never, and exit status1meant “findings athighor above”, not an error. - If you get
secretsfree: --fail-on got 'banana', expected critical, high, medium, low, or info.with exit status2, the level is misspelled. Use one of those five, ornever. - If
secretsfree: /Users/flavio/dev/recipe-bx is not a folder.comes back with exit status3, the path is wrong. Run the scan from the project root, or pass the right folder. - If
.envdoesn’t show up in the findings, the scan skipped it because Git ignores it. Add--include-ignored. - If an ignored finding keeps coming back, check the fingerprint in
.secretsfree.json.secretsfree ignoreaccepts any text without checking it, so a typo printsAdded fingerprintand changes nothing. A renamed file also gets a new fingerprint. - If the scan reports
Email addressor a/Users/<name>path you don’t care about, add--no-identity. Those come from the identity rules, not the credential ones. - If a key you deleted from the code still shows up as
history only, it’s in an old commit. Rotate it at the provider. Editing the file again won’t remove it.
Get Secrets Free
Find API keys, tokens, credentials files and identity leaks before they ship. A native Mac app and CLI with full MIT source.
See Secrets Free → · Read the docs · $20. See the app page for tax details, with full source code.
Want me to talk about your product? You can sponsor this site.