HC.SafeCommands 2.0.0

SafeCommands

A safe command gateway CLI for AI coding agents. Provides 162 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

Requires the .NET 10 runtime (SafeCommands 2.0+).

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 (reads + pr/issue create)
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.

Audit History (~/.safecommands/config.json)

To enable local invocation history, create ~/.safecommands/config.json in your OS user home directory (create the .safecommands directory first):

{
  "audit": true
}

Auditing is disabled by default. A missing file, absent audit property, or false disables it without creating audit files. Invalid or unreadable configuration disables auditing with a generic stderr diagnostic. Only a JSON boolean is accepted. Other properties are ignored; configuration cannot extend the command allowlist or change safety policies.

Each completed outer invocation appends one compact JSON line to ~/.safecommands/audit.log, including help and failed commands. Records contain schema version, UTC start time, canonical command (or a fixed meta/unknown category), argument count, working directory, OS username, process ID, elapsed milliseconds, exit code, and outcome (returned or threw). Argument count includes command tokens after removing SafeCommands' global --json flag. Recursive proxy run dispatch produces one record. Escaping exceptions have a null exit code; routing errors already converted to exit code 1 remain returned.

Privacy: argument values, option strings, output, exception text, and policy explanations are never logged. Unknown command tokens are not retained. Working directories and usernames still reveal local path and identity information. New files use private permissions, and existing permissions are restricted without granting additional access where supported.

Retention is fixed at three files total: audit.log, audit.log.1, and audit.log.2, each at most 10 MiB. Rotation and append share a persistent audit.log.lock file across cooperating processes; do not delete that lock file while commands run. Contention is limited to 250 ms. Incomplete trailing lines are discarded before the next append. Oversized records and failed writes are skipped with at most one generic stderr diagnostic per invocation, including in JSON mode. Audit failures do not change command stdout, return values, or exceptions.

This is best-effort completion history: forced termination may leave no record, filesystem operations can stall beyond the lock timeout, and flush/disposal does not guarantee survival of power loss. The current user can alter or remove history. Records do not authenticate an agent, identify exact argument-named resources, or distinguish policy denial from other failures by exit code alone. It is not a tamper-resistant security ledger.

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.