shellfirm: A CAPTCHA Between Your Shell and Destructive Commands
Safety guardrails for ai coding agents and human terminal commands
At a glance
- What is it?
- shellfirm is a Rust CLI that hooks into eight shells, matches commands against 100+ risk patterns, and forces a human to solve an arithmetic challenge before a dangerous command runs. It also ships an MCP server so AI coding agents can query it. Here is what it does, where it can fail, and who should skip it.
- Who is it for?
- Adopt shellfirm if you run a shared shell environment, work on production Kubernetes or cloud infrastructure from a terminal, or let an AI coding agent execute Bash commands on your behalf. Skip it if your workflow depends on non-interactive shell scripts, since a prompt-based interceptor cannot protect code paths where no human is present to answer the challenge.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 124 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Failure Mode shellfirm Targets: Fast Hands, Slow Regret
The README opens with a blunt framing: humans make mistakes, and AI agents make them faster. That is the problem shellfirm addresses. A single mistyped character in rm -rf ./src, or a --force flag added out of habit, can destroy work in under a second, and there is no undo. The project positions itself as an interception layer that sits between the shell and the command, forcing a deliberate pause before execution. The target user is not a beginner. It is an experienced engineer or a team that has already been burned once, or an organization deploying AI coding agents that execute shell commands without a human reviewing each one. The README's example output shows the framing clearly: a risky command triggers a warning block with severity, blast radius, a description, and an arithmetic challenge the user must solve to proceed.
How the Interception Works: Shell Hooks, Pattern Matching, and Blast Radius Scoring
shellfirm installs a hook into your shell's command pipeline. The README states that shellfirm init auto-detects the shell and sets up the hook, and that after restarting or sourcing your rc file, commands pass through shellfirm before execution. When a command matches one of the 100+ patterns across nine ecosystems (filesystem, git, Kubernetes, Terraform, Docker, AWS, GCP/Azure, Heroku, and databases), shellfirm blocks execution and presents a warning. The warning includes a severity level drawn from Critical, High, Medium, Low, or Info, and a blast radius classification such as [PROJECT] or [RESOURCE]. The blast radius is computed from runtime context signals, according to the README, and those signals also feed into risk scoring. Context-aware escalation means the challenge gets harder when you are connected via SSH, running as root, on a protected git branch, or inside a production Kubernetes cluster. The user must solve an arithmetic challenge to proceed, or press Ctrl+C to cancel. Every intercepted command and decision is logged as JSON-lines, which gives you an audit trail after the fact.
Getting It Installed and the Hook Running
Installation is available through three package managers. The npm route is npm install -g @shellfirm/cli. Homebrew users run brew tap kaplanelad/tap && brew install shellfirm. Rust users can run cargo install shellfirm. Binaries are also published on the releases page. After installation, shellfirm init sets up the shell hook and auto-detects your shell. You then restart the shell or source your rc file. The README suggests testing with git reset --hard, which should trigger a shellfirm warning. For manual setup and shell-specific instructions, including an Oh My Zsh plugin, the README points to the shell setup docs at shellfirm.vercel.app. Team policies are configured through a .shellfirm.yaml file in the project. The README describes this as additive-only, meaning project policies can add checks but never weaken the base configuration. That constraint matters: a team member cannot commit a .shellfirm.yaml that disables protections for everyone else.
Where shellfirm Stops Working: Non-Interactive Shells and Pattern Gaps
The most obvious limitation is that shellfirm is a prompt-based interceptor. If a command runs inside a non-interactive shell, such as a CI pipeline, a cron job, or a script invoked by another tool, there is no human present to solve the arithmetic challenge. The README does not describe a non-interactive bypass or a fail-closed mode for those contexts, so it is unclear whether shellfirm blocks, allows, or errors in that situation. That is a gap worth verifying before you rely on it as a safety net for automated systems. The second limitation is pattern coverage. The README claims 100+ patterns across nine ecosystems, but a pattern-based system only catches what it has patterns for. A custom deployment script that calls a proprietary CLI to delete cloud resources will not match any pattern unless you write one. The README mentions custom checks in the configuration docs, but the effort of maintaining those checks falls on you. Third, the arithmetic challenge is a speed bump, not a security control. Anyone who understands the pattern can solve 8 + 0 in under a second. It forces a pause, not a barrier.
The MCP Server: shellfirm as a Tool for Claude Code and Cursor
shellfirm ships an MCP server that exposes four tools: check_command, suggest_alternative, explain_risk, and get_policy. The README states that shellfirm connect claude-code sets up both hooks and MCP in one command. With hooks installed, every Bash command an agent issues is checked before execution, and risky commands are blocked. With MCP, the agent can call shellfirm tools to explain risks and suggest alternatives. The suggest_alternative tool is the more interesting one, because it turns a block into a redirect. The README's git push --force example shows the alternative git push --force-with-lease, with an explanation that it checks whether your local ref is up to date before force pushing. That is a concrete, actionable substitution rather than a generic warning. The MCP server also means shellfirm can be queried by agents that are not executing commands directly, which makes it useful as a risk-explanation layer even outside the shell hook.
How shellfirm Differs from a Wrapper Script or a Pre-Commit Hook
The closest alternative is a hand-rolled wrapper: a shell function or alias that checks for dangerous flags before running a command. The difference is scope and maintenance. A wrapper covers the commands you thought to wrap. shellfirm covers 100+ patterns across nine ecosystems out of the box, with context-aware escalation that a wrapper would have to reimplement. A pre-commit hook is a different tool entirely: it runs at commit time, not at command time, and it cannot stop an rm -rf that never touches git. The other comparison is to a full policy engine like Open Policy Agent, which evaluates structured input against Rego policies. OPA is more expressive and auditable, but it does not hook into your shell and it does not present an interactive challenge. shellfirm trades expressiveness for immediacy: it sits directly in the command path and forces a decision before the command runs. That trade-off is the point. If you need centralized policy enforcement across a fleet, shellfirm is not that. If you need a last line of defense at the terminal, it is.
Licence, Maintenance, and What to Verify Before Adopting
shellfirm is licensed under Apache-2.0, which permits commercial use, modification, and redistribution, provided you retain the licence and attribution notices. That is a permissive licence with an explicit patent grant, which matters if you are embedding shellfirm in a commercial product. The repository is not archived, and the most recent release listed is v0.3.10 from May 2026, with v0.3.9 and v0.3.8 before it. The version numbers are still in the 0.x range, which typically signals that the project has not committed to a stable API. The README does not describe a deprecation policy or a compatibility guarantee for the .shellfirm.yaml format or the MCP tool interfaces. If you adopt shellfirm, budget for the possibility that a future release changes configuration keys or tool signatures. The audit log format (JSON-lines) is simple enough to parse with standard tools, so that is a low-risk integration point. The higher-risk integration is the shell hook itself, which modifies your rc file. Back up your shell profile before running shellfirm init, and review the diff it produces.
Editorial conclusion
Adopt shellfirm if you run a shared shell environment, work on production Kubernetes or cloud infrastructure from a terminal, or let an AI coding agent execute Bash commands on your behalf. Skip it if your workflow depends on non-interactive shell scripts, since a prompt-based interceptor cannot protect code paths where no human is present to answer the challenge. Before installing, verify that your shell is on the supported list of eight, and check whether the pattern set covers the ecosystems you actually touch. Run shellfirm init on a throwaway shell profile first, then try git reset --hard to confirm the hook fires before you rely on it.
Community notes