AI-Native Workflow

Hush provides commands specifically designed for AI coding assistants. These let AI agents reason about your secrets without ever seeing the actual values.

Quick Start

Copy this prompt into your AI assistant to set up Hush:

Set up Hush for AI-native secrets management. Install @chriscode/hush,
configure SOPS/age encryption, create hush.yaml, and help me encrypt
my .env files. Never read .env files directly - use hush commands.

For more prompts, see the AI Prompts guide.

The Problem

When you ask an AI assistant to help with your project, it often needs to understand your configuration:

• “Set up the database connection”
• “Configure Stripe integration”
• “Check if the API key is set”

If you let the AI read your .env file directly, those secrets get sent to the LLM provider. That’s a security risk.

The Solution

Hush provides two AI-safe commands:

• hush inspect - Shows all variables with masked values
• hush has <key> - Checks if a specific variable exists

These commands give AI agents enough information to help without exposing secrets.

Commands for AI Agents

hush inspect

Shows all variables with masked values:

hush inspect

Output:

Secrets for development:

  DATABASE_URL      = post****************... (45 chars)
  STRIPE_SECRET_KEY = sk_t****************... (32 chars)
  API_KEY           = (not set)

Total: 3 variables

Target distribution:

  root (.) - 3 vars
  app (./app/) - 1 vars
    include: EXPO_PUBLIC_*
  api (./api/) - 2 vars
    exclude: EXPO_PUBLIC_*

The AI can see:

• Which variables exist
• Their approximate length
• Which are set vs unset
• Which targets receive which variables

But it never sees the actual values.

hush has

Check if a specific variable is set:

# Verbose output
hush has DATABASE_URL
# Output: DATABASE_URL is set (45 chars)

# Quiet mode (for scripting)
hush has DATABASE_URL -q
# Exit code: 0 (exists) or 1 (missing)

Use in conditional logic:

hush has STRIPE_SECRET_KEY -q && echo "Stripe is configured"
hush has DATABASE_URL -q || echo "Missing DATABASE_URL"

AI Agent Instructions

If you’re using AI coding assistants, add this to your project’s AI instructions:

## Secrets Management

This project uses Hush for secrets. NEVER read .env files directly.

Instead, use these commands:
- `hush inspect` - See what variables are configured
- `hush has <KEY>` - Check if a specific variable exists
- `hush status` - See configuration and file status

These commands mask sensitive values, making them safe to run.

Common AI Workflows

”Help me set up the database”

1. AI runs hush inspect to see current variables
2. AI sees DATABASE_URL = (not set)
3. AI provides instructions for adding the variable
4. Human adds the value and runs hush encrypt

”Check if Stripe is configured”

hush has STRIPE_SECRET_KEY -q && echo "Ready" || echo "Missing"

AI gets a clear yes/no without seeing the key.

”What environment variables does the API need?”

hush inspect -e production

AI sees which variables exist for production and which targets receive them.

Example Conversation

Human: Can you help configure the payment integration?

AI: Let me check your current secrets configuration.

hush inspect

I can see you have:

• STRIPE_SECRET_KEY - Set (32 chars)
• STRIPE_WEBHOOK_SECRET - Not set
• STRIPE_PUBLISHABLE_KEY - Not set

You’re missing the webhook secret and publishable key. Here’s how to add them:

1. Get your keys from the Stripe dashboard
2. Add them to .env:

   STRIPE_WEBHOOK_SECRET=whsec_xxx
   STRIPE_PUBLISHABLE_KEY=pk_xxx

3. Encrypt: hush encrypt

Tip

The AI helped configure Stripe without ever seeing the actual API keys.

Cursor Integration

For Cursor, add to your .cursorrules:

# Secrets
- Never read .env, .env.*, or .dev.vars files directly
- Use `hush inspect` to see variable names and status
- Use `hush has <KEY>` to check specific variables
- These commands mask values, making them safe to share

Claude Integration

For Claude’s project knowledge:

# Environment Variables

This project uses Hush for encrypted secrets management.

Safe commands (these mask values):
- hush inspect - List all variables with masked values
- hush has <KEY> - Check if a variable exists
- hush status - Show configuration

Never run:
- cat .env
- echo $SECRET_KEY
- Any command that would expose actual values

Claude Code / OpenCode Skill

For Claude Code or OpenCode users, Hush includes a ready-to-use Agent Skill that automatically teaches the AI to use Hush commands instead of reading .env files directly.

Installation

The easiest way to install the skill is with the hush skill command:

npx hush skill           # Interactive: choose global or local
npx hush skill --global  # Install to ~/.claude/skills/ (all projects)
npx hush skill --local   # Install to ./.claude/skills/ (this project)

Global vs Local:

• Global (~/.claude/skills/) - Works across all your projects. Recommended for personal use.
• Local (./.claude/skills/) - Bundled with the project. Recommended for teams (commit to git).

Tip

For teams, use --local and commit the .claude/ directory so everyone gets the skill automatically.

How It Works

Once installed, Claude Code automatically:

1. Detects when you’re working with secrets, environment variables, or .env files
2. Loads the Hush skill instructions
3. Uses hush inspect and hush has instead of reading files directly
4. Guides you through adding or modifying secrets safely

What the Skill Teaches Claude

• Never read .env, .env.*, .env.local, or .dev.vars files
• Use hush inspect to see what variables exist (with masked values)
• Use hush has <KEY> to check if specific secrets are configured
• Use hush set to help users add or modify secrets
• Guide users through hush encrypt after changes

Tip

The skill uses Claude Code’s “allowed-tools” feature to restrict Claude to only Hush-related bash commands when the skill is active, providing an extra layer of protection.

Skill Files

The skill uses progressive disclosure - only loading detailed docs when needed:

File	Purpose
SKILL.md	Core rules and daily commands (always loaded)
SETUP.md	First-time setup instructions (loaded if Hush not configured)
REFERENCE.md	Detailed command reference (loaded when needed)
examples/workflows.md	Step-by-step workflow examples

Note

For more copy-paste prompts for common tasks, see the AI Prompts guide.

Security Considerations

What AI Sees

With hush inspect:

• Variable names
• Whether they’re set or unset
• Character length (approximate)
• First 4 characters (masked: sk_t***...)

What AI Never Sees

• Full secret values
• Complete connection strings
• API keys or tokens
• Passwords

Why This Matters

Even if your AI conversation is logged:

• No secrets in the logs
• No risk of accidental exposure
• Audit-friendly workflow

Note

The first 4 characters are shown to help identify the type of secret (e.g., sk_ for Stripe keys, ghp_ for GitHub tokens). This is intentional and mirrors what you’d see in dashboards.