https://github.com/kaplanelad/shellfirm
Safety guardrails for ai coding agents and human terminal commands
https://github.com/kaplanelad/shellfirm
agent ai captcha devops devops-tools mcp prompt rust shell terminal zsh
Last synced: about 24 hours ago
JSON representation
Safety guardrails for ai coding agents and human terminal commands
- Host: GitHub
- URL: https://github.com/kaplanelad/shellfirm
- Owner: kaplanelad
- License: apache-2.0
- Created: 2021-12-24T19:00:12.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2026-03-06T06:41:21.000Z (7 days ago)
- Last Synced: 2026-03-06T09:53:31.009Z (7 days ago)
- Topics: agent, ai, captcha, devops, devops-tools, mcp, prompt, rust, shell, terminal, zsh
- Language: Rust
- Homepage: https://shellfirm.vercel.app/
- Size: 1.28 MB
- Stars: 882
- Watchers: 4
- Forks: 28
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-security - shellfirm - It is a handy utility to help avoid running dangerous commands with an extra approval step. You will immediately get a small prompt challenge that will double verify your action when risky patterns are detected. (Terminal / Development)
- awesome-zsh-plugins - shellfirm - Shellfirm is a handy utility to help avoid running dangerous commands without an extra step of approval. When risky patterns is detected you will immediately get a small prompt challenge that will verify your action. (Plugins / ZSH on Windows)
- fucking-awesome-zsh-plugins - shellfirm - Shellfirm is a handy utility to help avoid running dangerous commands without an extra step of approval. When risky patterns is detected you will immediately get a small prompt challenge that will verify your action. (Plugins / ZSH on Windows)
- awesome-cli-agents - kaplanelad/shellfirm - Safety guardrails for ai coding agents and human terminal commands [Terminal] (882⭐) (🚀 AI Tools for Vim, Neovim, and Terminal)
README
# 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 Agent Integration
shellfirm ships as an [MCP](https://modelcontextprotocol.io/) server so AI coding agents can check commands before running them.
### 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 |
### MCP Setup
#### Claude Code
Add to `~/.claude.json` (global) or `.claude.json` (per-project):
```json
{
"mcpServers": {
"shellfirm": {
"command": "shellfirm",
"args": ["mcp"]
}
}
}
```
For Cursor, Windsurf, Zed, Cline, Continue, Amazon Q, and other MCP-compatible tools, see the [integration guides](https://shellfirm.vercel.app/docs/agents-and-automation/cursor-and-others).
---
## 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 --install
```
**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.dev/docs/getting-started/shell-setup).
---
## Documentation
Full documentation is available at **[shellfirm.dev](https://shellfirm.dev)**:
- [Configuration](https://shellfirm.dev/docs/configuration) — challenge types, severity thresholds, custom checks
- [Context-Aware Protection](https://shellfirm.dev/docs/context-aware) — SSH, root, git branches, Kubernetes, environment variables
- [Team Policies](https://shellfirm.dev/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)