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.yamlproject-level rules - AI Agents & Automation — MCP server, LLM analysis, agent mode
Contributing
Contributions are welcome! Please open an issue or pull request on GitHub.