# Claude Secrets
A secure secrets management plugin for Claude Code and MCP clients. Enables AI assistants to safely handle credentials with user approval, automatic redaction, and secret capture from command output.
## Features
- **Secret Injection** - Use `{{SECRET_NAME}}` placeholders in commands to inject secrets
- **Session-Based Permissions** - User approves secret access per-session with time-based expiry
- **Output Redaction** - Automatically redacts known secrets and common patterns from output
- **Secret Capture** - Extract secrets from command output (e.g., AWS session tokens) and store for future use
- **LLM-Friendly Metadata** - Descriptions help future LLMs discover and use the right secrets
- **macOS Menu Bar App** - Native notifications and dialogs for secret requests
- **Encrypted Vault** - Secrets stored with Fernet encryption
## Installation
### One-Line Install (Recommended)
```bash
curl -sSL https://raw.githubusercontent.com/henghonglee/claude-secrets/main/install.sh | bash
```
This automatically:
- Installs the package via pipx
- Creates the encrypted vault
- Installs the Claude Code plugin
- Starts the menu bar app
- Enables auto-start on login
### Manual Installation
```bash
pipx install git+https://github.com/henghonglee/claude-secrets.git
ccs init
```
### From Source
```bash
git clone https://github.com/henghonglee/claude-secrets.git
cd claude-secrets
pip install -e .
ccs init
```
## Quick Start
```bash
# Initialize vault + start menubar + enable auto-start on login
ccs init
# Add a secret with description (helps LLMs understand what it's for)
ccs add AWS_ACCESS_KEY
# Check status
ccs status
```
The `init` command automatically:
- Creates the encrypted vault
- Installs the Claude Code plugin (via marketplace)
- Starts the menu bar app
- Enables auto-start on login (macOS)
### Plugin-Only Install (if claude-secrets is already installed)
```bash
claude plugin marketplace add henghonglee/claude-secrets
claude plugin install claude-secrets@henghonglee-claude-secrets
```
## Claude Code Commands
When installed as a plugin:
| Command | Description |
|---------|-------------|
| `/claude-secrets:list` | List all available secrets |
| `/claude-secrets:add [NAME]` | Add a new secret |
| `/claude-secrets:run <command>` | Run a command with secret injection |
## MCP Configuration (Non-Plugin)
For Claude Desktop or other MCP clients, add to your configuration:
```json
{
"mcpServers": {
"secrets": {
"command": "ccs",
"args": ["serve"]
}
}
}
```
## MCP Tools
### `run_command`
Execute a CLI command with secret injection and output redaction.
```json
{
"command": "aws s3 ls --profile {{AWS_PROFILE}}",
"timeout": 60,
"capture": [
{
"path": "$.Credentials.SecretAccessKey",
"name": "AWS_SESSION_SECRET",
"description": "Temporary AWS secret key from STS. Use with AWS_SESSION_KEY_ID and AWS_SESSION_TOKEN.",
"expires_at": "2024-01-24T12:00:00Z"
}
]
}
```
**Parameters:**
- `command` - Command with `{{SECRET_NAME}}` placeholders
- `timeout` - Timeout in seconds (default: 60)
- `capture` - Extract secrets from JSON output:
- `path` - JSONPath expression (e.g., `$.Credentials.SecretAccessKey`)
- `name` - Name for the captured secret
- `description` - LLM-friendly description
- `expires_at` - ISO 8601 expiration timestamp
- `redact_patterns` - Additional regex patterns to redact
- `skip_builtin_patterns` - Skip built-in redaction patterns
### `list_secrets`
List available secrets with their descriptions.
```json
{
"tag": "aws"
}
```
Returns:
```json
{
"secrets": [
{
"name": "AWS_ACCESS_KEY",
"description": "AWS access key for production account",
"expires_at": null
}
]
}
```
### `request_secret`
Request the user to add a missing secret via the menu bar app.
```json
{
"name": "GITHUB_TOKEN",
"description": "Personal access token for GitHub API. Needs repo and workflow scopes."
}
```
The menu bar app will show a native macOS dialog prompting the user to enter the secret value.
### `get_permissions`
Get current session permission status for secrets.
## How It Works
1. **Client LLM calls `list_secrets`** to discover available secrets
2. **LLM constructs command** with `{{SECRET_NAME}}` placeholders
3. **User approves** secret access when prompted (cached for session)
4. **Server injects secrets** and executes command
5. **Output is redacted** before returning to LLM
6. **Captured secrets** are stored with LLM-provided descriptions for future use
## Menu Bar App (macOS)
The menu bar app provides:
- Server status indicator
- List of stored secrets with expiry times
- Native dialogs for secret requests
- Notifications when secrets are captured or expiring
Start with:
```bash
claude-secrets-menubar
```
## Security Model
- **Encrypted storage** - Vault encrypted with Fernet (AES-128-CBC)
- **Permission prompts** - User must approve each secret's use
- **Session expiry** - Permissions auto-expire (default: 1 hour)
- **Output redaction** - Secrets automatically removed from command output
- **Audit logging** - All secret access logged to `~/.claude-secrets/audit.log`
## Uninstalling
### One-Line Uninstall
```bash
curl -sSL https://raw.githubusercontent.com/henghonglee/claude-secrets/main/uninstall.sh | bash
```
### Manual Uninstall
```bash
ccs uninstall # Stops menubar, removes plugin, keeps secrets
pipx uninstall claude-secrets
```
### Delete Everything (including secrets)
```bash
ccs uninstall --delete-vault
pipx uninstall claude-secrets
```
Your secrets are preserved by default in `~/.claude-secrets/` so you can reinstall later without losing them.
## Plugin Structure
```
claude-secrets/
├── .claude-plugin/
│ ├── plugin.json # Plugin manifest
│ └── marketplace.json # Marketplace manifest (for plugin distribution)
├── .mcp.json # MCP server configuration
├── skills/
│ └── secrets/
│ └── SKILL.md # Teaches Claude when/how to use secrets
├── commands/
│ ├── list.md # /claude-secrets:list command
│ ├── add.md # /claude-secrets:add command
│ └── run.md # /claude-secrets:run command
└── src/
└── claude_secrets/ # Python package
```
## Configuration
Configuration stored at `~/.claude-secrets/config.json`:
```json
{
"session_timeout": 3600
}
```
Set values with:
```bash
ccs config set session_timeout 7200
```
## Development
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=claude_secrets
# Test plugin locally
claude --plugin-dir ./
```
## License
MIT
