# 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): ```bash 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 ```bash npm install -g @shellfirm/cli ``` ### Homebrew ```bash brew tap kaplanelad/tap && brew install shellfirm ``` ### Cargo ```bash cargo install shellfirm ``` Or download the binary from the [releases page](https://github.com/kaplanelad/shellfirm/releases). --- ## Quick Start **1. Install the shell hook** (auto-detects your shell): ```bash shellfirm init ``` **2. Restart your shell** (or `source` your rc file). **3. Try it:** ```bash git reset --hard # Should trigger shellfirm! ``` For manual setup, shell-specific instructions, and Oh My Zsh plugin, see the [shell setup docs](https://shellfirm.vercel.app/docs/getting-started/shell-setup). --- ## Documentation Full documentation is available at **[shellfirm.vercel.app](https://shellfirm.vercel.app)**: - [Configuration](https://shellfirm.vercel.app/docs/configuration) — challenge types, severity thresholds, custom checks - [Context-Aware Protection](https://shellfirm.vercel.app/docs/context-aware) — SSH, root, git branches, Kubernetes, environment variables - [Team Policies](https://shellfirm.vercel.app/docs/team-policies) — `.shellfirm.yaml` project-level rules - [AI Agents & Automation](https://shellfirm.vercel.app/docs/agents-and-automation) — MCP server, LLM analysis, agent mode --- ## Contributing Contributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/kaplanelad/shellfirm). ## License [Apache-2.0](LICENSE)