gitwtfhub

wtf is bash-guard?

dabit3/bash-guard — explained in plain English

Analysis updated 2026-05-18

43ShellAudience · developerComplexity · 2/5Setup · easy

TL;DR

A shell hook that blocks risky commands like sudo, rm, or mkfs before AI coding agents can run them.

Mindmap

mindmap
  root((Bash Guard))
    What it does
      Blocks risky shell commands
      Runs before agent tool use
      Rejects with explanation
    Tech stack
      Bash
      jq
    Use cases
      Block sudo and mkfs
      Block destructive rm mv
      Protect coding agents
    Audience
      Developers using AI agents
    Setup
      Copy script locally
      Add hook to agent config

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Prevent an AI coding agent from accidentally running sudo or destructive commands

REASON 2

Block rm, mv, or rsync commands that target paths outside the current project

REASON 3

Add a safety checkpoint before shell commands in Claude Code, Codex CLI, or Devin CLI

REASON 4

Adapt the hook for other agents that support JSON-based command hooks

What's in the stack?

ShellBashjq

How it stacks up

dabit3/bash-guardfivetaku/fablizechitransh-cj/kimchi
Stars434342
LanguageShellShellShell
Setup difficultyeasyeasyeasy
Complexity2/52/52/5
Audiencedeveloperdevelopervibe coder

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · easy Time to first run · 5min

Only needs Bash and jq, setup is copying a script and editing one JSON config file.

Wtf does this do

Bash Guard is a small safety hook that stops risky shell commands before an AI coding agent gets to run them. It works with agents that support a PreToolUse hook, which is a checkpoint that runs right before a tool executes, including Claude Code, Codex CLI, and Devin CLI. Instead of trusting the agent to always run safe commands, this script sits in front of the terminal and checks each one first. It blocks two kinds of commands. First, anything that uses sudo, diskutil, or mkfs, which are commands that can change system-level settings or reformat storage. Second, destructive commands like rm, mv, rsync, or shred, but only when they are pointed at paths outside the current project folder, so normal file operations inside your project still work fine. To install it, you copy the bash-guard.sh script into a local folder and make it executable. Then you add a small JSON snippet to your coding agent's configuration file, telling it to run this script before every shell command. The exact configuration file and matcher pattern differ slightly by agent: Claude Code, Codex CLI, and Devin CLI each have their own settings file and hook format, and the README lists all three. After updating the configuration, you restart the agent, and in Codex CLI you also need to open its hooks menu to trust the new hook. Once installed, Bash Guard runs automatically and silently for every command the agent tries to run. Safe commands pass through without any change in behavior. Blocked commands are rejected with an explanation instead of running. The tool only requires Bash and the jq command-line JSON processor, so there is nothing else to install. It can also be adapted by other agents that pass command and working-directory information as JSON and respect a blocking exit status.

Yoink these prompts

Prompt 1
Help me install bash-guard and wire it into my Claude Code settings.json.
Prompt 2
Explain what commands bash-guard blocks and why.
Prompt 3
Show me how to test bash-guard by piping a sample hook payload into it.
Prompt 4
Adapt bash-guard's matcher pattern for use with Codex CLI instead of Claude Code.

Frequently asked questions

wtf is bash-guard?

A shell hook that blocks risky commands like sudo, rm, or mkfs before AI coding agents can run them.

What language is bash-guard written in?

Mainly Shell. The stack also includes Shell, Bash, jq.

How hard is bash-guard to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is bash-guard for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.