envshed agent

Set up an AI coding agent so secrets are less likely to end up in the chat. envshed agent install adds two hooks and a skill. Claude Code is the only agent supported today.

This reduces accidental leaks. It is not a security boundary.

Hooks run on your machine and can be worked around. An agent with shell access can reach anything your user can, for example by copying .env to another name and reading the copy. Limits that must hold, such as who can read production, belong on the server: use roles and scoped service tokens for those.

Usage

terminal

envshed agent install [options]
envshed agent uninstall [options]

Options

Option	Description
--agent <name>	Agent to configure. Default: claude-code.
--scope <scope>	user or project. Default: user.
--output json	Print a single JSON document

What gets installed

	--scope user	--scope project
Settings	~/.claude/settings.json	.claude/settings.json
Skill	~/.claude/skills/envshed-agent-safety/SKILL.md	.claude/skills/envshed-agent-safety/SKILL.md

The user scope follows CLAUDE_CONFIG_DIR when it is set. The project scope uses the Git repository root, or the current directory outside a repository.

Hooks:

• UserPromptSubmit stops a prompt that looks like it contains a secret.
• PreToolUse stops tool calls that would bring a secret value into the session.

Skill: rules for the agent. Never ask for a secret in chat, use envshed request and envshed run, and never print values. It is separate from the general envshed skill and does not change it.

Install merges with your settings and keeps everything already there. It is safe to run again: nothing changes if nothing is out of date. If the settings file is not valid JSON, the command stops and leaves it alone. Restart the agent afterwards.

Uninstall removes only Envshed's own hook entries and skill. A skill file at that path that Envshed did not write is never overwritten or removed.

The envshed command must be on PATH

Hooks call the CLI directly and never use npx, because that can reach the network. Install it with npm install -g envshed.

• User scope: if the envshed on your PATH is a different build, the hooks call this build by its full path instead. Run install again after moving or reinstalling the CLI.
• Project scope: the file is shared, so hooks always call plain envshed, and each teammate needs it installed. Without it, their agent shows a hook error and keeps working unprotected.

What is blocked

Prompts

A prompt is stopped when it contains:

• A known token format, such as those from GitHub, GitLab, AWS, Stripe, Slack, Google, npm, Anthropic, OpenAI or Envshed, a JWT, a private key, or a URL with a password.
• A sensitive assignment, such as DB_PASSWORD=... or "apiKey": "...".
• A phrase that introduces a password in English, Portuguese or Spanish, such as "the password is ...", "a senha é ..." or "la contraseña es ...". This covers passwords with no recognizable format.
• A long, high-entropy string.

Git SHAs, other hex hashes, UUIDs, lockfile integrity strings, URLs without credentials, file paths and identifiers are ignored. So are sentences such as "the password is wrong".

The message names the rule that matched and never repeats the value or any part of it.

A blocked prompt can still be on disk

The prompt does not reach the model, but Claude Code still writes what you typed to its local session files and prompt history. If you pasted a real secret, rotate it.

Tool calls

Blocked	Use instead
envshed secret get	envshed run -- <command>
envshed pull --stdout, and envshed pull -f aimed at the terminal: -, /dev/stdout, /dev/stderr, /dev/tty or /dev/fd/N	envshed run -- <command>
envshed diff --show-values	envshed diff
envshed share open without --file, or with --file aimed at the terminal	envshed share open --file <path>
envshed run -- printenv, envshed run -- env, and shell or script one-liners that print the environment	envshed run -- <command>
Turning off agent mode, which masks values in envshed run output: envshed run --no-redact, or setting ENVSHED_AGENT_MODE, unsetting CLAUDE_CODE_CHILD_SESSION or running env -i in front of envshed or a shell such as bash -c (also as a bare assignment, or through export or unset)	envshed run -- <command>
Reading .env, .env.local, .envrc or prod.env with the Read or Grep tools, or with shell commands such as cat, head, grep, sed and source. This includes globs and braces the shell expands to those names, such as cat .en?, cat .e* or cat .{env,x}	envshed run -- <command>, or read .env.example
Reading files under ~/.envshed/ or the envshed keychain entries, which hold the CLI token	Nothing: envshed commands use them on their own

These stay allowed: envshed run -- npm test, envshed pull -f .env.local, ENVSHED_AGENT_MODE=1, .env.example, .env.sample, .env.template, cp .env.example .env, ls .env, and anything that only mentions .env in text, such as grep -r process.env src or a commit message. A glob that matches every file, such as grep TODO *, is not blocked either, in the same way as grep -r TODO ..

False positives

In a prompt, add envshed:allow anywhere in the text and send it again:

output

envshed:allow the fixture below is not a real key: ...

For patterns you see often, add them to .envshed-allow. That file holds patterns, never values.

How the hooks run

The hook commands read the event as JSON on stdin and work offline. They make no network calls, do not read your token, write nothing to disk and start in about 40 ms. Because they do not read your CLI config, their messages use the language from LC_ALL or LANG.

A hook failure never locks you out. If a hook crashes or gets input it cannot read, it prints one line on stderr and exits with code 1. Claude Code shows that as a hook error and lets the action continue, unchecked.

Requirements

Claude Code with support for suppressOriginalPrompt, which keeps your text out of the block message. It was tested on version 2.1.314.