HC.SafeCommands 0.3.0

SafeCommands

A safe command gateway CLI for AI coding agents. Provides 160 pre-validated commands across 12 groups so agents can be allowlisted on safe without per-command approval overhead.

Why?

AI coding agents (Claude Code, Cursor, Gemini CLI, Codex, etc.) need to run CLI commands as part of their workflow, but many commands have dangerous modes:

• git checkout . silently destroys all uncommitted work
• rm -rf can expand beyond its target (deleted a user's entire home directory)
• prisma db push --force-reset dropped 60+ production database tables
• terraform destroy wiped 2.5 years of production data
• npm install executes arbitrary postinstall scripts (supply chain attacks)

These aren't theoretical risks. Research across 70+ documented incidents from Claude Code, Gemini CLI, Cursor, Codex, and Replit GitHub issues showed these exact commands causing real data loss.

SafeCommands solves this by providing a curated command surface where every operation is pre-validated for safety. Allowlist safe once, and all commands through it are guaranteed safe by design.

Installation

dotnet tool install --global HC.SafeCommands

To update:

dotnet tool update --global HC.SafeCommands

Quick Start

safe help                    # Show all command groups
safe git status              # Git status (read-only)
safe git add myfile.cs       # Stage specific file (blocks 'git add .')
safe git commit -m "msg"     # Commit (blocks --no-verify, --amend)
safe dotnet build             # Build project
safe dotnet test              # Run tests
safe file delete-temp         # Clean bin/obj/node_modules/etc.
safe process kill-port 3000   # Kill process on port
safe generate uuid             # Generate a v4 UUID
safe generate secret           # Crypto-random base64 secret
safe help git                 # Show all git commands with safety levels

Command Groups

Safety Levels

Every command has a safety classification:

What's Blocked

Based on real-world incident research, SafeCommands explicitly prevents:

JSON Output

All commands support --json for machine-readable output, designed for AI agent consumption:

safe git status --json

{
  "branch": "main",
  "clean": true,
  "files": []
}

safe env check node --json

{
  "tool": "node",
  "available": true,
  "version": "v22.12.0"
}

AI Agent Integration

Setup

Run safe instructions to print CLAUDE.md-ready integration text, or auto-install it:

safe instructions --install    # Appends to your project's CLAUDE.md

Claude Code

Add to your project's CLAUDE.md:

## SafeCommands
Use `safe` for all CLI operations. Run `safe help` for available commands.

Then allowlist all groups in .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(safe help:*)",
      "Bash(safe version:*)",
      "Bash(safe instructions:*)",
      "Bash(safe git:*)",
      "Bash(safe file:*)",
      "Bash(safe process:*)",
      "Bash(safe docker:*)",
      "Bash(safe npm:*)",
      "Bash(safe pnpm:*)",
      "Bash(safe bun:*)",
      "Bash(safe dotnet:*)",
      "Bash(safe db:*)",
      "Bash(safe env:*)",
      "Bash(safe generate:*)",
      "Bash(safe proxy:*)"
    ]
  }
}

Or run safe instructions which outputs a ready-to-use allowlist that stays in sync with the installed version.

Other Agents

For any agent that supports command allowlisting, allowlist the safe command groups and include the output of safe instructions in the agent's context.

Proxy System

The proxy system allows safe access to tools not in the main groups:

safe proxy gh pr list              # GitHub CLI (read-only operations)
safe proxy az account show         # Azure CLI (read-only)
safe proxy kubectl get pods        # Kubernetes (read-only)
safe proxy terraform plan          # Terraform (plan only, no apply/destroy)
safe proxy curl https://example.com  # HTTP GET only (no POST/PUT/DELETE)
safe proxy cargo build             # Rust cargo
safe proxy pip list                # Python pip
safe proxy make                    # Make targets

Each proxy tool has its own allowlist of permitted subcommands and flags.

Configuration

Built-in Allowlist (Immutable)

The core command allowlist is compiled into the binary. It cannot be modified by prompt injection, config file manipulation, or any external input.

Extension Config (~/.safecommands/config.json)

Optional extension configuration for adding custom safe commands, additional npm script names, process names, or safe directories:

{
  "version": 1,
  "allowedScripts": ["storybook", "e2e"],
  "allowedProcessNames": ["ruby"],
  "safeDirs": [".angular/cache"]
}

For Developers

Building from Source

git clone https://github.com/hansen-consultancy/SafeCommands.git
cd SafeCommands
dotnet build src/SafeCommands
dotnet run --project src/SafeCommands -- help

Installing Locally

cd src/SafeCommands
dotnet pack
dotnet tool install --global --add-source ./nupkg HC.SafeCommands

Architecture

• Registry-based: All commands defined in CommandRegistry with metadata (group, name, safety level, handler)
• No shell interpretation: Uses ProcessStartInfo.ArgumentList to prevent injection
• Cross-platform: Windows, macOS, Linux via RuntimeInformation.IsOSPlatform()
• SpectreConsole: Rich terminal output with color-coded safety levels

Adding Commands

Each command group is a static class in Commands/ that registers its commands:

static class MyCommands
{
    public static void Register(List<CommandDefinition> commands)
    {
        commands.Add(new("mygroup", "mycommand", "Description",
            "safe mygroup mycommand [args]", SafetyLevel.ReadOnly,
            (args, json) => { /* handler */ return 0; }));
    }
}

Then register it in CommandRegistry.Initialize().

License

This project is licensed under the MIT License.