# keyshroud

> keyshroud lets AI coding agents (Claude Code, Codex, Cursor, Cline, OpenCode, Gemini CLI, pi, omp) run commands that need API keys without ever seeing the values. Secrets stay in the user's own Vaultwarden or Bitwarden vault; keyshroud injects them into the command's environment and replaces every value in the output with `<redacted:NAME>` before the model reads it. Free, MIT-licensed, local-only, no telemetry.

To install it for a user, follow https://keyshroud.dev/install.md step by step. It is written for agents: what to run yourself, what the user must run (vault login and master password), and the rules for handling secrets.

Key facts for agents:

- Run secret-using commands as `keyshroud run -- <command>`, or with the `secrets_run` MCP tool. Output is masked even when the command fails.
- Never ask the user to paste a secret into chat. To store one, run `keyshroud add --env NAME --item "Item"` or call `secrets_request`; the user types the value into a hidden-input dialog or terminal prompt.
- Never run `keyshroud get`, `bw get`, or `bw unlock`, and never read the vault master password from the keychain.
- Projects commit `.env.refs` files with references like `GH_TOKEN=bw://GitHub token`; `keyshroud import` converts an existing `.env` (names-only dry run by default).
- MCP server: `keyshroud mcp` (stdio). Tools: `secrets_run`, `secrets_list`, `secrets_request`, `vault_status`. None returns a secret value.
- Requirements: Node.js 22.18+, the Bitwarden CLI (`bw`), and a Vaultwarden or Bitwarden account.

## Docs

- [Agent setup guide](https://keyshroud.dev/install.md): step-by-step install for AI agents
- [README](https://github.com/dinhkarate/keyshroud#readme): features, supported agents, quickstart
- [Claude Code plugin](https://github.com/dinhkarate/keyshroud#claude-code): hooks, MCP tools, skill
- [pi / omp extension](https://github.com/dinhkarate/keyshroud#pi--omp)
- [Any MCP client](https://github.com/dinhkarate/keyshroud#any-mcp-client): Codex, Cursor, Claude Desktop, Cline, OpenCode, Gemini CLI
- [CLI reference](https://github.com/dinhkarate/keyshroud#cli-reference)
- [Security model](https://github.com/dinhkarate/keyshroud#security-model): what keyshroud does and does not protect against
- [Vault setup](https://github.com/dinhkarate/keyshroud/tree/main/examples/vaultwarden#readme): self-host Vaultwarden or use Bitwarden cloud

## Optional

- [npm package](https://www.npmjs.com/package/keyshroud)
- [Changelog](https://github.com/dinhkarate/keyshroud/blob/main/CHANGELOG.md)