safe-chains

Agentic coding tools prompt you dozens of times for commands like git log --oneline | head -20, cargo test && cargo clippy -- -D warnings, or even find src -name "*.rs" -exec grep -l "TODO" {} \; | sort | while read f; do echo "=== $f ==="; grep -n "TODO" "$f"; done. You approve them all, and eventually stop reading the prompts, which is exactly when a destructive command slips through.

safe-chains parses these commands (pipes, chains, loops, subshells, nested wrappers) and auto-approves them when every segment is verifiably safe. The prompts that remain are the ones worth reading.

It covers 458 commands with flag-level validation, compound command parsing, and recursive subshell expansion, all deterministic, with no AI in the loop. If safe-chains isn’t sure, it doesn’t guess. It leaves the prompt for you.

safe-chains works as a Claude Code pre-hook, a CLI tool, or an OpenCode plugin.

How it works

Overview
Security

Command reference

Overview — glossary and category index
Adding Commands — how to contribute new commands

Installation

Homebrew (macOS)

brew install michaeldhopkins/tap/safe-chains

Pre-built binary

Download signed, notarized binaries from GitHub Releases. Available for macOS (Apple Silicon and Intel) and Linux (x86_64 and aarch64).

curl -L https://github.com/michaeldhopkins/safe-chains/releases/latest/download/safe-chains-aarch64-apple-darwin.tar.gz | tar xz
mv safe-chains ~/.cargo/bin/

With Cargo

cargo install safe-chains

From source

git clone [email protected]:michaeldhopkins/safe-chains.git
cd safe-chains
cargo install --path .

Configuration

Claude Code

Run safe-chains --setup to automatically configure the hook in ~/.claude/settings.json. Or manually add:

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "safe-chains"
        }
      ]
    }
  ]
}

Restart your Claude Code sessions to activate the hook. Updating the safe-chains binary takes effect immediately.

Cleaning up approved commands

Once safe-chains is active, most of your existing Bash(...) approved commands in ~/.claude/settings.json and .claude/settings.local.json are redundant. safe-chains already handles them with stricter, flag-level validation.

More importantly, broad patterns can weaken your security. A pattern like Bash(bash *) will approve bash -c "rm -rf /" — Claude Code matches the pattern before safe-chains gets a chance to recursively validate the inner command.

Review your approved commands and remove any that safe-chains covers. A good prompt for this:

Find every .claude folder on my system — ~/.claude, any .claude
folders at the top of my projects directory, and .claude folders
inside individual repos. For each settings.json and
settings.local.json, check every Bash(...) pattern against
safe-chains (run `safe-chains "command"` to test). Flag overly
broad patterns like Bash(bash *) or Bash(sh *) that bypass
safe-chains' recursive validation. Present me with a suggested
list of changes for each file before making any edits.

Or, to clear out all approved Bash commands from every Claude settings file at once:

find ~/.claude ~/projects -maxdepth 4 -name 'settings*.json' -path '*/.claude/*' | while read f; do
  jq '
    if .approved_commands then .approved_commands |= map(select(startswith("Bash(") | not)) else . end |
    if .permissions.allow then .permissions.allow |= map(select(startswith("Bash(") | not)) else . end
  ' "$f" > "$f.tmp" && mv "$f.tmp" "$f" && echo "Cleaned $f"
done

This removes every Bash(...) entry but leaves non-Bash permissions (WebFetch, Edit, etc.) untouched.

OpenCode (experimental)

Generate OpenCode permission.bash rules from safe-chains’ command list:

safe-chains --opencode-config > opencode.json

Usage

Claude Code (hook mode)

With the hook configured, safe-chains reads JSON from stdin and responds with a permission decision. No arguments needed.

CLI mode

Pass a command as a positional argument. Exit code 0 means safe, exit code 1 means unsafe.

safe-chains "ls -la | head -5"    # exit 0 = safe
safe-chains "rm -rf /"            # exit 1 = unsafe

Safety Levels

Every allowed command is classified into one of three safety levels:

Level	Description	Examples
`inert`	Pure read/display, no code execution	`cat`, `grep`, `ls`, `git log`
`safe-read`	Executes code but read-only	`cargo test`, `rspec`, `npm test`
`safe-write`	May modify files but considered safe	`cargo build`, `go build`

Use --level to set a threshold. Only commands at or below the threshold pass:

safe-chains --level inert "cat foo"          # exit 0 (inert <= inert)
safe-chains --level inert "cargo test"       # exit 1 (safe-read > inert)
safe-chains --level safe-read "cargo test"   # exit 0 (safe-read <= safe-read)
safe-chains --level safe-read "cargo build"  # exit 1 (safe-write > safe-read)

Without --level, the default threshold is safe-write (all allowed commands pass).

Levels propagate through pipelines, wrappers, and substitutions — a pipeline’s level is the maximum of its components.

How It Works

Built-in rules

safe-chains knows 458 commands. For each one it validates specific subcommands and flags, allowing git log but not git push, allowing sed 's/foo/bar/' but not sed -i.

Parsing example

Take this command from the introduction:

find src -name "*.rs" -exec grep -l "TODO" {} \; | sort | while read f; do echo "=== $f ==="; grep -n "TODO" "$f"; done

safe-chains parses this and validates every leaf:

Pipeline segment 1: find src -name "*.rs" -exec grep -l "TODO" {} \;
- find is allowed with positional predicates
- -exec triggers delegation: the inner command grep -l "TODO" {} is extracted and validated separately
- grep -l passes (-l is an allowed flag)
Pipeline segment 2: sort passes (safe with any arguments)
Pipeline segment 3: while read f; do ...; done is a compound command, parsed recursively:
- read f passes (shell builtin)
- echo "=== $f ===" passes
- grep -n "TODO" "$f" passes (-n is an allowed flag)

Every leaf is safe, so the entire command is approved.

Compound commands

Shell compound commands (for/while/until loops and if/elif/else conditionals) are parsed and each leaf command is validated recursively, supporting arbitrary nesting depth.

Output redirection (>, >>) to /dev/null is inert. Output redirection to other files is allowed at safe-write level. Input redirection (<), here-strings (<<<), and here-documents (<<, <<-) are allowed.

Backticks and command substitution ($(...)) are recursively validated.

Interaction with approved commands

safe-chains runs as a pre-hook. If it approves, Claude Code skips the prompt. If it doesn’t recognize the command, Claude Code’s normal permission flow takes over (checking your Bash(...) patterns in settings, or prompting).

Where this gets interesting is chained commands. Claude Code matches approved patterns against the full command string. If you approved Bash(cargo test:*) and Claude runs cargo test && ./generate-docs.sh, Claude Code won’t match — the full string isn’t just cargo test.

safe-chains splits the chain and checks each segment independently. cargo test passes built-in rules. ./generate-docs.sh matches Bash(./generate-docs.sh:*) from your settings. Both segments covered, chain auto-approved.

Once safe-chains is handling your safe commands, most of your existing approved patterns are redundant. Strip them down to project-specific scripts and tools safe-chains doesn’t know about. See Cleaning up approved commands.

For example, given cargo test && npm run build && ./generate-docs.sh:

cargo test passes built-in rules
npm run build matches Bash(npm run:*) from settings
./generate-docs.sh matches Bash(./generate-docs.sh:*) from settings

Security

safe-chains is an allowlist-only command checker. It auto-approves bash commands that it can verify as safe. Any command not explicitly recognized is left for the human to approve.

What it prevents

Auto-approval of destructive, write, or state-changing commands. An agentic tool cannot use safe-chains to bypass permission prompts for rm, git push, sed -i, curl -X POST, or any command/flag combination not in the allowlist.

Security properties

Allowlist-only. Unrecognized commands are never approved.

Per-segment validation. Commands with shell operators (&&, |, ;, &) are split into segments. Each segment must independently pass validation. One safe segment cannot cause another to be approved.

Redirection handling. Output redirection (>, >>) to /dev/null is inert. Output redirection to any other file is allowed at safe-write level. Input redirection (<), here-strings (<<<), and here-documents (<<, <<-) are allowed.

Substitution validation. Command substitutions ($(...)) are extracted and recursively validated. echo $(git log) is approved because git log is safe. echo $(rm -rf /) is not. bash -c and sh -c recursively validate their arguments.

No shell evaluation. eval, exec, source, and . (dot-source) are never approved when they would execute arbitrary commands.

Settings guardrails. When matching commands against your Claude Code settings patterns, segments containing >, <, backticks, or $() are never approved via settings, even if a pattern matches. This prevents Bash(./script *) from approving ./script > /etc/passwd.

Term	Meaning
Allowed standalone flags	Flags that take no value (`--verbose`, `-v`). Listed on flat commands.
Flags	Same as standalone flags, but in the shorter format used within subcommand entries.
Allowed valued flags	Flags that require a value (`--output file`, `-j 4`).
Valued	Same as valued flags, in shorter format within subcommand entries.
Bare invocation allowed	The command can be run with no arguments at all.
Subcommands	Named subcommands that are allowed (e.g. `git log`, `cargo test`).
Positional arguments only	No specific flags are listed; only positional arguments are accepted.
(requires –flag)	A guarded subcommand that is only allowed when a specific flag is present (e.g. `cargo fmt` requires `--check`).

Keyboard shortcuts

safe-chains