safe-chains

Agentic coding tools prompt you dozens of times per session 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 approves only when every segment is verifiably safe. Now, you only get prompted to approve a command when something interesting comes along.

safe-chains covers 1568 commands with flag-level validation, compound command parsing, and recursive subshell expansion, all deterministically, not based on a model’s guess like with Claude’s auto mode.

How it works

With your agent harness configured to run safe-chains from a hook, each Bash command is analyzed and gets a decision response.

Or, just run safe-chains yourself in your terminal to learn about a command. It’s fun!

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

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 /usr/local/bin/   # or anywhere in your PATH

With Cargo

cargo install safe-chains

From source

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

Configuration

safe-chains integrates with multiple agentic CLI coding tools. List the supported targets with:

safe-chains --list-tools

Install for a specific tool:

safe-chains --setup                   # default: Claude Code
safe-chains --setup --tool=codex      # Codex (OpenAI)
safe-chains --setup --auto-detect     # install for every detected tool

Claude Code

Run safe-chains --setup (or --setup --tool=claude) 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.

For project-specific scripts or in-house CLIs safe-chains doesn’t ship a definition for, Custom Commands are an alternative to broad Bash(...) approvals — same flag-level validation as built-ins.

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.

Codex (OpenAI)

Run safe-chains --setup --tool=codex to write ~/.codex/hooks.json with safe-chains as a PreToolUse hook. Or manually add to ~/.codex/hooks.json:

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

Codex requires [features] codex_hooks = true in ~/.codex/config.toml for hooks to fire. Add it manually if it isn’t already there:

[features]
codex_hooks = true

Restart your Codex sessions after the first install. Updating the safe-chains binary takes effect immediately.

Cursor CLI

Cursor exposes a dedicated beforeShellExecution event that fires only on shell calls — cleaner than a generic pre-tool hook. Run safe-chains --setup --tool=cursor to install. The config goes to ~/.cursor/hooks.json:

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": "safe-chains hook cursor",
        "timeout": 30
      }
    ]
  }
}

Cursor hooks fail-open by default. If you want safe-chains failures to block (rather than silently letting commands through), add "failClosed": true to the entry.

Gemini CLI

Run safe-chains --setup --tool=gemini to write ~/.gemini/settings.json. Gemini’s hook event is BeforeTool (PascalCase) and the response key is decision (allow / deny — there’s no ask). Manual config:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "^run_shell_command$",
        "hooks": [
          {
            "type": "command",
            "command": "safe-chains hook gemini",
            "timeout": 60000
          }
        ]
      }
    ]
  }
}

Note Gemini’s timeout is in milliseconds (other vendors use seconds).

Qwen Code

Run safe-chains --setup --tool=qwen to write ~/.qwen/settings.json. Qwen mirrors Claude Code’s hook envelope verbatim. Manual config:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "safe-chains hook qwen",
            "timeout": 60000
          }
        ]
      }
    ]
  }
}

Factory Droid

Run safe-chains --setup --tool=droid to write ~/.factory/settings.json. Droid’s bash tool is named Execute (not Bash), and Droid requires absolute paths for hook commands — the installer resolves the safe-chains binary’s absolute path at install time. Manual config (substitute the absolute path of your safe-chains binary):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Execute",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/safe-chains hook droid",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

GitHub Copilot CLI

Copilot’s hook config lives in .github/hooks/*.json (per-repo) or ~/.github/hooks/*.json (user-global, files merge). Run safe-chains --setup --tool=copilot to write ~/.github/hooks/safe-chains.json. Copilot’s quirks: the response is a flat object (no hookSpecificOutput wrapper), the script-path field is bash (not command), and toolArgs is a JSON-encoded string on stdin (the safe-chains adapter double-decodes it). Manual config (substitute absolute path):

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "/usr/local/bin/safe-chains hook copilot",
        "comment": "safe-chains: validate every Bash tool call before it runs.",
        "timeoutSec": 60
      }
    ]
  }
}

As of late 2025 only permissionDecision: "deny" is honored by Copilot’s permission system; safe-chains emits "allow" envelopes anyway so future Copilot releases that honor the full schema get the upgrade for free.

OpenCode (experimental)

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

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

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.

Custom Commands

safe-chains ships definitions for hundreds of tools. If your project uses an in-house CLI it doesn’t recognize, or you want to disallow a built-in command for a specific project, drop a TOML file in either of these locations:

.safe-chains.toml in your repo root (or any parent directory)
~/.config/safe-chains.toml for definitions that apply across all your projects

When a command appears in more than one custom definition, the more local definition is used.

Add a tool safe-chains doesn’t know

# .safe-chains.toml

[[command]]
name = "myco"
description = "MyCo internal CLI"
url = "https://wiki.myco/cli"
bare_flags = ["--help", "--version", "-h", "-v"]

[[command.sub]]
name = "deploy"
level = "SafeWrite"
standalone = ["--help", "--dry-run", "-h"]
valued = ["--env", "--region"]
max_positional = 1

[[command.sub]]
name = "status"
standalone = ["--help", "--watch", "-h", "-w"]
valued = ["--env"]

[[command.sub]]
name = "logs"
standalone = ["--help", "--follow", "-f"]
valued = ["--service", "--since", "--lines"]

This allows myco --help, myco deploy --dry-run staging, myco status --env prod, and so on. Anything outside the listed flags or subcommands is denied.

The schema mirrors the built-in TOMLs — every field documented in commands/SAMPLE.toml works in custom files.

A shell script

# ~/.config/safe-chains.toml

[[command]]
name = "generate-docs.sh"
bare = true
max_positional = 0

Names match the command’s basename. ./generate-docs.sh, bin/generate-docs.sh, and generate-docs.sh all look up the same entry.

Disallow a built-in command for this project

[[command]]
name = "gh"
deny = true

Three lines and gh is denied in this project — bare invocation, subcommands, and every flag.

Generate one with an AI

Paste your tool’s --help output and this prompt into Claude or another LLM:

Generate a safe-chains custom command definition. Use the schema in https://github.com/michaeldhopkins/safe-chains/blob/main/commands/SAMPLE.toml. Output a single TOML block I can paste into .safe-chains.toml. Cover read-only and idempotent subcommands; omit destructive ones.

Skipping custom files: `SAFE_CHAINS_NO_LOCAL`

Set SAFE_CHAINS_NO_LOCAL=1 to skip the project-local walk and the user-level lookup. Two reasons:

Debugging. If a custom definition might be interfering with a command, run with the bypass to compare against built-in behavior:

SAFE_CHAINS_NO_LOCAL=1 safe-chains "your command"

Slow filesystems. Each invocation makes a few stat() calls walking up from the current directory. On a local SSD this is microseconds. On network mounts (NFS, corporate file shares), WSL1 with files on the Windows side, or under aggressive antivirus, each stat() can cost tens of milliseconds. If you don’t use custom commands and you’re on one of those filesystems, export the variable in your shell init:

export SAFE_CHAINS_NO_LOCAL=1

Now safe-chains skips the lookup entirely.

How It Works

Built-in rules

safe-chains knows 1568 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

Normally, you would be prompted to run this by your agent, and you would have to run some sort of auto- or permission-skipping mode to not be prompted, which could allow anything to be run.

Running from a hook, 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 auto-approved without over-extending permissions to the agent.

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 — or write a Custom Command for those scripts and let safe-chains validate them with the same flag-level rules it applies to built-ins. 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 that are independently evaluated. All segments must return safe to approve the command.

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.

What it does not prevent

Information disclosure: read-only commands can read sensitive files (cat ~/.ssh/id_rsa). Sensitive contents would be read by the model provider. We recommend pairing safe-chains with a hook to block reading ~/.ssh, ../credentials and similar directories.
Unrecognized commands: commands safe-chains doesn’t handle are passed through to the normal permission flow for your harness.
Chaining with broad approvals: if you add patterns like Bash(bash *) to your Claude Code settings, safe-chains will match them per-segment without recursive validation, matching Claude Code’s own behavior. See Cleaning up approved commands.

Testing approach

Every command handler is covered by multiple layers of automated testing. Each handler includes explicit safe/denied test cases covering expected approvals and rejections. Every command has a spec suite. Every type of data definition in safe-chains has a test suite.

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