shellfirm

Think before you execute.

Humans make mistakes. AI agents make them faster. shellfirm intercepts dangerous shell commands before the damage is done — for both.

$ rm -rf ./src
============ RISKY COMMAND DETECTED ============
Severity: Critical
Blast radius: [PROJECT] — Deletes 347 files (12.4 MB) in ./src
Description: You are going to delete everything in the path.

Solve the challenge: 8 + 0 = ? (^C to cancel)

$ git push origin main --force
============ RISKY COMMAND DETECTED ============
Severity: High
Blast radius: [RESOURCE] — Force-pushes branch main (3 commits behind remote)
Description: This command will force push and overwrite remote history.
Alternative: git push --force-with-lease
  (Checks that your local ref is up-to-date before force pushing, preventing accidental overwrites of others' work.)

Solve the challenge: 3 + 5 = ? (^C to cancel)

Features

100+ patterns across 9 ecosystems (filesystem, git, Kubernetes, Terraform, Docker, AWS, GCP/Azure, Heroku, databases)
8 shells — Zsh, Bash, Fish, Nushell, PowerShell, Elvish, Xonsh, Oils
Context-aware escalation — harder challenges when connected via SSH, running as root, on protected git branches, or in production Kubernetes clusters
Safe alternative suggestions — actionable safer commands shown alongside every warning
Severity levels with configurable thresholds (Critical, High, Medium, Low, Info)
Project policies — share team safety rules via .shellfirm.yaml (additive-only, never weakens)
Audit trail — every intercepted command and decision logged as JSON-lines
Blast radius detection — runtime context signals feed into risk scoring
MCP server — expose shellfirm as an AI tool for Claude Code, Cursor, and other agents

AI Tool Integration

Claude Code

One command sets up both automatic safety (hooks) and on-demand analysis (MCP):

shellfirm connect claude-code

This adds:

Hooks — every Bash command is checked before execution; risky commands are blocked
MCP — Claude can call shellfirm tools to explain risks and suggest alternatives

MCP Tools

| Tool | Description | |------|-------------| | check_command | Check if a command is risky — returns severity, matched rules, and alternatives | | suggest_alternative | Get safer replacement commands | | explain_risk | Detailed explanation of why a command is dangerous | | get_policy | Read the active shellfirm configuration and project policy |

Installation

npm

npm install -g @shellfirm/cli

Homebrew

brew tap kaplanelad/tap && brew install shellfirm

Cargo

cargo install shellfirm

Or download the binary from the releases page.

Quick Start

1. Install the shell hook (auto-detects your shell):

shellfirm init --install

2. Restart your shell (or source your rc file).

3. Try it:

git reset --hard  # Should trigger shellfirm!

For manual setup, shell-specific instructions, and Oh My Zsh plugin, see the shell setup docs.

Documentation

Full documentation is available at shellfirm.dev:

Configuration — challenge types, severity thresholds, custom checks
Context-Aware Protection — SSH, root, git branches, Kubernetes, environment variables
Team Policies — .shellfirm.yaml project-level rules
AI Agents & Automation — MCP server, LLM analysis, agent mode

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

License

Apache-2.0

Shellfirm

Install / Use

README