Safe Mode

Risk-based permission enforcement wrapper for Claude CLI. Restricts CLI operations based on configurable risk thresholds by parsing permission blocks from plugin SAFEGUARDS.md files.

Quick Start

# Run with auto-discovery at safe level (read-only operations only)
claude-safe -d

# Run at caution level (allows creates/updates)
claude-safe -d -l caution

# Preview permissions without running (dry-run)
claude-safe -d -n -v

# Specify plugins manually
claude-safe -l warning -p "/path/to/plugin1:/path/to/plugin2"

Risk Levels

Operations are classified into four cumulative risk levels:

Threshold Logic: Operations with riskvalue <= threshold go to allow[], operations with riskvalue > threshold go to deny[].

CLI Reference

claude-safe [OPTIONS] [-- CLAUDE_ARGS...]

Options:
  -d, --discover        Auto-discover plugins from ~/.claude/plugins/cache/
  -l, --level LEVEL     Risk level: safe|caution|warning|danger (default: safe)
  -p, --plugins DIRS    Colon-separated plugin directories
  -n, --dry-run         Preview permissions without running claude
  -v, --verbose         Debug output
  -h, --help            Show help message

Environment Variables:
  CLAUDE_SAFE_LEVEL     Default risk level (overridden by -l)
  CLAUDE_SAFE_PLUGINS   Default plugin directories (overridden by -p)
  CLAUDE_HOME           Claude config directory (default: ~/.claude)

Adding Permission Blocks

Add a YAML permission block to your plugin's SAFEGUARDS.md file:

<!-- PERMISSIONS
permissions:
  cli: your-cli-name
  operations:
    - pattern: "your-cli list *"
      risk: safe
    - pattern: "your-cli create *"
      risk: caution
    - pattern: "your-cli delete *"
      risk: warning
    - pattern: "your-cli drop *"
      risk: danger
-->

SAFEGUARDS.md Search Order:

1. {plugin}/skills/shared/docs/SAFEGUARDS.md
2. {plugin}/docs/SAFEGUARDS.md
3. {plugin}/.claude/SAFEGUARDS.md
4. {plugin}/SAFEGUARDS.md

Pattern Format

Patterns use simple wildcards and convert to Bash() permission format:

Usage Examples

Production Safety (Default)

# Only allow read operations
claude-safe -d

Development Mode

# Allow creates and updates
claude-safe -d -l caution

Testing Mode

# Allow deletes (but not bulk/purge)
claude-safe -d -l warning

Full Access (Use with Caution)

# Allow all operations including dangerous ones
claude-safe -d -l danger

Preview Before Running

# See what would be allowed/denied
claude-safe -d -n -v -l caution

Pass Arguments to Claude

# Use specific model
claude-safe -d -l caution -- --model sonnet

# Start with a prompt
claude-safe -d -- "Help me search for errors"

Dependencies

• bash 4.0+
• yq (YAML parser)
• jq (JSON processor)

Install on macOS:

brew install yq jq

Integration with Existing Plugins

The following plugins have permission blocks in their SAFEGUARDS.md:

See Also

• [Permission Block Template](docs/PERMISSION_TEMPLATE.md) - Copy-paste template for new plugins
• [Risk Level Guidelines](docs/RISK_GUIDELINES.md) - How to classify operations