Let agents run freely. Everything is reversible.

Safe shell operations with automatic checkpoints for AI agents.

curl -fsSL https://raw.githubusercontent.com/qhkm/safeshell/main/install.sh | bash

Then restart your terminal. That's it.

AI agents (Claude Code, Cursor, etc.) run shell commands. Sometimes they make mistakes:

rm -rf ./src          # Oops, wrong directory
mv config.json old/   # Overwrote something important

SafeShell catches these by creating automatic backups before any destructive command:

rm important-file.txt
# [safeshell] Checkpoint created: 2024-12-12T143022-a1b2c3

# Oh no! Get it back:
safeshell rollback --last
# ✓ Rollback complete!

# Core
safeshell list              # See all checkpoints
safeshell rollback --last   # Undo the last destructive command
safeshell rollback <id>     # Rollback to specific checkpoint
safeshell status            # Show stats

# Cleanup
safeshell clean             # Remove old checkpoints (based on retention_days)
safeshell clean --keep 10   # Keep only 10 most recent
safeshell clean --older-than 3d  # Remove checkpoints older than 3 days

# Configuration
safeshell config            # View all settings
safeshell config get <key>  # Get a setting
safeshell config set <key> <value>  # Change a setting

# Automatic cleanup
safeshell schedule          # View schedule status
safeshell schedule enable   # Enable daily auto-cleanup (midnight)
safeshell schedule enable --hourly --keep 20  # Hourly, keep 20
safeshell schedule disable  # Disable auto-cleanup

# Setup
safeshell disable           # Revert to normal binaries
safeshell enable            # Re-enable SafeShell protection
safeshell upgrade           # Upgrade to latest version

We evaluated several approaches to make AI agents safer:

We chose Shell Aliases because:

• ✅ Zero setup complexity (one curl command)
• ✅ No root/sudo required
• ✅ Works on any macOS/Linux system
• ✅ Minimal performance overhead
• ✅ Easy to understand and debug
• ✅ Hard links = zero extra disk space

The tradeoff is that only aliased commands are protected. But in practice, rm, mv, cp, chmod, and chown cover 95% of destructive operations that AI agents perform.

You run:  rm -rf ./build
              ↓
SafeShell:  Backup files → Execute command
              ↓
Mistake?    safeshell rollback --last
              ↓
Files:      Restored ✓

Zero overhead: Uses hard links (same inode, no extra disk space).

Add to your system prompt:

SafeShell is installed. If you make a destructive mistake, run:
safeshell rollback --last

SafeShell includes an MCP (Model Context Protocol) server that lets AI agents interact with checkpoints directly - no shell commands needed.

Add to your Claude Code MCP settings (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "safeshell": {
      "command": "safeshell",
      "args": ["mcp"]
    }
  }
}

Agent: "I need to delete the build folder. Let me create a checkpoint first."
→ Uses checkpoint_create(paths: ["./build"], reason: "before cleanup")

Agent: "Now deleting..."
→ Runs rm -rf ./build

Agent: "Oops, that was the wrong folder!"
→ Uses checkpoint_rollback(id: "latest")

Agent: "Files restored. Let me try again with the correct path."

• Proactive safety: Agent creates checkpoint BEFORE destructive operations
• Direct integration: No shell parsing needed
• Rich context: Include reasons for checkpoints
• Better control: Query what's protected, selective rollback

brew install safeshell/tap/safeshell

go install github.com/qhkm/safeshell@latest
safeshell init
source ~/.zshrc

git clone https://github.com/qhkm/safeshell
cd safeshell
make install
safeshell init
source ~/.zshrc

curl -fsSL https://raw.githubusercontent.com/qhkm/safeshell/main/uninstall.sh | bash

View and modify settings with safeshell config:

safeshell config                        # View all
safeshell config set retention_days 3   # Change cleanup threshold
safeshell config set max_storage_mb 2000  # Limit to 2GB

Or edit ~/.safeshell/config.yaml directly:

# Storage limits
max_storage_mb: 5000       # Total storage limit (default: 5GB)
max_file_size_mb: 100      # Skip files larger than this (default: 100MB)
max_checkpoints: 100       # Maximum checkpoints to keep

# Cleanup
retention_days: 7          # 'safeshell clean' removes older than this

# Security
warn_sensitive_files: true # Warn when backing up .env, *.pem, etc.
sensitive_patterns:        # Patterns that trigger warnings
  - ".env"
  - "*.pem"
  - "*.key"
  - "id_rsa"

# Exclusions (never backed up)
exclude_paths:
  - "node_modules/*"
  - ".git/objects/*"
  - "*.tmp"

# Commands that trigger automatic checkpoints
wrapped_commands:
  - rm
  - mv
  - cp
  - chmod
  - chown

• Beginner's Guide - Complete guide for new users
• Contributing Guide - How to contribute to SafeShell

The name SafeShell is inspired by SafeTensors from Hugging Face.

SafeTensors solved a critical problem in ML: pickle files could execute arbitrary code when loaded, making model sharing dangerous. Their solution? A simple, safe format that just stores tensors - nothing executable, nothing dangerous.

We saw a parallel problem emerging with AI agents. As agents like Claude Code and Cursor gain the ability to execute shell commands, they can accidentally cause real damage - deleted files, overwritten configs, broken systems. The traditional approach of "ask permission for everything" breaks the flow and defeats the purpose of autonomous agents.

SafeShell applies the same philosophy: instead of restricting what agents can do, make everything safely reversible. Let them run freely, experiment boldly, and fix mistakes instantly.

Just as SafeTensors made ML model sharing safe by design, SafeShell makes AI agent operations safe by design.

"The best safety is invisible safety."

Apache 2.0