secret-box Claude Code mod: hide secrets from Claude Code as it uses them

secret-box is a community mod by Ray Amjad (ray-amjad), published in his claude-code-mods repository. It aims to hide secrets from Claude Code without stopping Claude from using them. A key that reaches the conversation stays in the transcript, so the mod keeps it out in both directions.

• In. Claude calls a request_secret tool with a variable name and a one-line reason. A masked box opens, you paste the key, and the mod writes NAME=value to .env (or a file such as .env.local) and adds that file to .gitignore if git does not already ignore it. Claude gets the name and a placeholder.
• Use. A placeholder written in a Bash, Write, Edit, MultiEdit or NotebookEdit call turns into the real value as the tool runs.
• Out. Tool results, prompts, attachments and subagent tasks are scanned. Vendor-shaped keys, high-entropy tokens, passwords on command lines and in connection strings, and every secret-named value in .env come back as placeholders.
• Never committed. git add of a .env file and a git commit that would include one are refused.

Emails and public IP addresses are hidden only if you turn on the pii option.

The install block above adds the author's marketplace and installs the plugin from it. Mods load only in a folder you have trusted, so accept the trust prompt first. To ask for the box, tell Claude billing.js needs the Stripe secret key, or use the secret box to ask me for STRIPE_SECRET_KEY.

hooks/hooks.json loads one module, register.jsx, which calls the redaction code in redact.ts and detect.ts and adds the box and the .env guard. The box waits for you in short sleep 0.3 processes, because a hook has a 10 second budget of its own time but time inside a mods API call is not counted. This is the commit guard, from register.jsx:

on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
  const why = await commitBlockReason($, String(e.command || ''))
  return why ? { deny: `secret-box: ${why} A pushed key can't be taken back.` } : next(e)
}).catch(() => ({ deny: 'secret-box: the .env guard failed, so this call is blocked to be safe.' }))

On every tool call, redact.ts swaps placeholders for real values (only in the tools listed in restoreTools), runs the tool, scans the result, and swaps keys it finds for placeholders. A Bash command that runs git commit, git tag or gh issue/gh pr gets no real values, so a commit message keeps the placeholder. The placeholder-to-value vault lives in memory and is not written to disk. Before a tool reads a .env file, a hook reads it too and hands each secret-named value to the vault, so even a plain word password is hidden.

Open /plugin configure secret-box@claude-code-mods, or set pluginConfigs in your user settings. The options are:

• secrets (on) and pii (off), with hideEmails and redactPrivateIps for what pii covers.
• restoreInToolInputs and restoreTools (default Bash,Write,Edit,MultiEdit,NotebookEdit). The option text warns never to list a tool that sends input to a model or the network, such as Agent, WebFetch or WebSearch.
• notify, minEntropy (3.6), minLength (24) and contextMinEntropy (3.0).
• Allow and deny lists: allow, allowEmails, allowPrefixes, allowUrlHosts and denyPrefixes.

We read the manifest, hooks.json, register.jsx, redact.ts in full, and detect.ts lines 1 to 823 and 1585 to 1657. The middle of detect.ts is detector regular expressions and helper code that we searched for network, process, eval, dynamic import and globalThis use rather than reading line by line. We listed the PNG images and the example app without running them. There is no package.json, no install script, no dependency, no binary and no minified code. Findings:

• Network: none. No fetch, sockets or $.http anywhere. The URLs in detect.ts are patterns it matches (Slack and Discord webhooks).
• Processes ($.process.run): sleep 0.3 while the box waits (on Windows node -e or ping), git ls-files --error-unmatch, git check-ignore -q, git diff --cached --name-only and git ls-files --modified --others --exclude-standard. All are argv arrays with no shell.
• File writes: only the env file you approve in the box (a bare name matching .env or .env.<name>, never a path) and the project's .gitignore. It refuses a file git tracks. Nothing under ~/.claude, shell files or LaunchAgents.
• File reads: .env files named in a Bash, Read, Grep or Edit call, and .env in the working directory at session start. Values are kept in memory only.
• Daemons and telemetry: none.
• Gating: it rewrites and can deny prompts, tool calls, attachments, @ mentions and subagent spawns. Its .catch handlers fail closed, so a crash withholds a result or drops a prompt instead of passing raw text. It refuses @.env, git add of .env, and a git commit that would include one.
• Real values go to tools: placeholders become real keys inside Bash, Write and Edit. A file Claude writes with a placeholder holds the real key. It refuses to put a value containing shell-active characters into a Bash command.
• Prompt injection: the request_secret description tells Claude to use it instead of asking you to paste a secret. That is the stated purpose. No hidden Unicode found.
• External requirements: none. It needs an interactive session and, for the dock, a terminal of at least 144 columns; otherwise it uses the band above the prompt (Ctrl+X, then Tab).
• License: MIT, with a LICENSE file in the repo root.

claude plugin validate passed with no manifest errors or warnings. It reported one non-blocking directory finding: no plugin icon. claude plugin test ran 46 tests across 3 files, and all passed.

The README's Limits section lists what to expect. In auto mode, Claude Code's classifier may block cat .env before secret-box sees it, though the placeholder still works. A .env value under 8 characters is hidden in .env reads but not everywhere else. Only the working directory's .env is learned at session start. Editing in the middle of the box with the arrow keys is not tracked. If the box does not appear, widen the terminal or press Ctrl+X, then Tab. Placeholders from an earlier session mean nothing in a new one.

To try it, copy the author's example folder to a scratch directory, run git init, and ask Claude to set up STRIPE_SECRET_KEY. Paste a fake key and then run cat .env to see the placeholder.