safe-mode

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:

Level	Value	Description	Typical Operations
`safe`	0	Read-only, no data modification	search, list, get, view, status
`caution`	1	Modifiable but easily reversible	create, update, enable, disable
`warning`	2	Destructive but potentially recoverable	delete (single items)
`danger`	3	IRREVERSIBLE data loss	bulk delete, drop, purge, uninstall

Threshold Logic: Operations with risk_value <= threshold go to allow[], operations with risk_value > 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:

{plugin}/skills/shared/docs/SAFEGUARDS.md
{plugin}/docs/SAFEGUARDS.md
{plugin}/.claude/SAFEGUARDS.md
{plugin}/SAFEGUARDS.md

Pattern Format

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

Pattern	Converted To
`splunk-as search *`	`Bash(splunk-as search *)`
`glab mr list *`	`Bash(glab mr list *)`
`confluence page delete *`	`Bash(confluence page delete *)`

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:

Plugin	CLI	Safe Ops	Danger Ops
Splunk-Assistant-Skills	`splunk-as`	search, metadata, list	app uninstall, kvstore drop
Jira-Assistant-Skills	`jira-as`	issue get, search	bulk delete, project delete
GitLab-Assistant-Skills	`glab`	mr list, issue view	repo delete
Confluence-Assistant-Skills	`confluence`	page get, search	space delete, purge

About this skill