shellfirm

Think before you execute.

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

$ 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

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.vercel.app:

• 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