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 1618 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 /", because 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.

Grok CLI (xAI)

Run safe-chains --setup --tool=grok to write ~/.grok/hooks/safe-chains.json. Grok’s shell tool is run_terminal_command, matched by Bash. Manual config:

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

A Grok hook can only block a command — an allowing hook “declines to deny” rather than granting it, so safe-chains vetoes commands it doesn’t recognize and leaves safe ones to Grok’s own approval flow (same as Cursor and Codex).

One extra setup step. Grok auto-loads your ~/.claude/settings.json hooks for Claude compatibility. If safe-chains is also installed for Claude Code, Grok will additionally run the Claude hook on every command — it can’t read Grok’s request format, so it does nothing (harmless, but noisy). Silence it by adding to ~/.grok/config.toml:

[compat.claude]
hooks = false

Antigravity CLI (`agy`)

Run safe-chains --setup --tool=antigravity to write ~/.gemini/config/hooks.json. Antigravity matches its shell tool by the name run_command. Manual config:

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

Note: Google sunset the Gemini CLI on June 18, 2026 and directs users to the Antigravity CLI (agy).

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, so 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 ~/.copilot/hooks/*.json (user-global, files merge). Run safe-chains --setup --tool=copilot to write ~/.copilot/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 v1.0.71, Copilot honors both permissionDecision: "allow" and "deny".

OpenCode

We’d love to support OpenCode, but it currently has no way to run this kind of hook. You could hand-build a static permission.bash allowlist from safe-chains’ command list, but we don’t recommend it: a fixed list is brittle, inflexible, and by now impractically long. If OpenCode’s hook situation changes, please open an issue and we’ll take a look.

Safety Levels

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

Level	Description	Examples
`paranoid`	Barely touches anything; no file access	`expr 1 + 1`, `true`
`reader`	Observes local or remote state; reads peer projects	`cat`, `grep -r`, `git status`, `cargo test`
`editor`	Creates or overwrites local files; no deletion	`touch`, `echo x > f`
`developer`	Runs your project; deletes your own files (default)	`cargo build`, `rm -rf ./node_modules`
`local-admin`	Runs as root on this machine	`sudo systemctl restart nginx`
`network-admin`	Operates your remotes: push, deploy, provision	`git push`
`yolo`	Everything except unbounded irreversible destruction	`dd if=/dev/zero of=./f`

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

safe-chains --level paranoid "expr 1 + 1"    # exit 0 (paranoid <= paranoid)
safe-chains --level paranoid "cat foo"       # exit 1 (reader > paranoid)
safe-chains --level reader "cat foo"         # exit 0 (reader <= reader)
safe-chains --level reader "cargo build"     # exit 1 (developer > reader)

Without --level, the default threshold is developer (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. To add an in-house CLI or disallow a built-in command, write a TOML file in one of two places:

~/.config/safe-chains.toml: applies everywhere, trusted automatically.
.safe-chains.toml in a repo (or any parent directory): applies to that project, once you trust the directory.

When a command is defined in both, a trusted project definition overrides the user-level one.

Project files must be trusted

A repo’s .safe-chains.toml sits inside the code safe-chains checks, and whatever edits the repo can edit that file. safe-chains ignores it until you pin the directory in your user config:

# ~/.config/safe-chains.toml
[[trusted]]
path = "/Users/you/work/acme"
sha256 = "9f2b…"   # shasum -a 256 acme/.safe-chains.toml

safe-chains honors the project file only while its contents match sha256. A change to the file un-trusts it until you review the change and trust it again.

Home directory level config (~/.config/safe-chains.toml and ~/.claude/settings.json) is trusted without pinning. Be careful granting access to these directories.

Granting trust requires a manual edit for now.

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.

Let safe-chains write it: `--suggest`

For a command safe-chains doesn’t recognize, --suggest writes (or upgrades) your local .safe-chains.toml for you. Pass the command you want to support as the argument:

safe-chains --suggest "acmedeploy --env prod ./service"

It writes a scoped [[command]] to .safe-chains.toml — allowing exactly the flags and positional count you ran, nothing more — and prints the [[trusted]] pin to paste into ~/.config/safe-chains.toml. safe-chains never edits your user config, so the command stays inert until you add that pin by hand.

The generated level defaults to "SafeWrite"; change it to "SafeRead" or "Inert" if the tool is lighter, then re-hash. --suggest only helps with commands safe-chains doesn’t know — for a recognized command that’s denied by a flag, subcommand, or path, it says so rather than generating a bypass.

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.

If you paste it into a repo’s .safe-chains.toml, pin the directory afterward (see Project files must be trusted).

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 1618 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.

Files by location

When you run a bash command, in addition to checking the safety of the actual command, safe-chains checks the directory the command wants to affect. Generally, commands are approved when they operate within the current working directory (from where you are running the agent, like ~/projects/abc). It also approves some read and write locations outside of that, like /tmp.

If you run an agent from a high-level directory like ~/, you give it a lot of power. This is the case whether or not you run safe-chains. Careful!

cat ./src/main.rs         # approved: inside your working directory
echo hi > ./out.txt       # approved: writing inside the project
grep -r TODO ./src        # approved
cat /tmp/scratch.txt      # approved: /tmp is scratch
cat /etc/hosts            # not approved: outside the project; you're prompted
cat ~/.ssh/id_rsa         # not approved: a credential
cp notes.txt /etc/x       # not approved: writing outside the project

safe-chains allows reaching into sibling directories of the current working directory. E.g., when working in ~/projects/webapp, otherwise safe commands in ~/projects/mobileapp would be auto-approved, except deleting a sibling’s files. “Nephew” directories (e.g. ~/projects/mobileapp/android/config) are also approved. This does not apply when you’re working in children of user folders, root, etc.

Trusted directories

If you always want to allow reading and writing in additional directories, add them to ~/.config/safe-chains.toml with read = true and/or write = true. The binary will pick up these preferences. safe-chains has a special block to not auto-allow writes to ~/.config/safe-chains.toml. This is because currently, most harnesses don’t have a protected way for third party hooks to store preferences.

# Work across every project under ~/projects, not just the current one
[[grant]]
path = "~/projects/"
read = true
write = true

# A scripts directory the agent both runs and edits
[[grant]]
path = "~/.runner-scripts/"
read = true
write = true

# Read a toolchain's install dir, but never let the agent write to it
[[grant]]
path = "~/.local/share/mise/"
read = true

Dot files are generally not part of allowlisted target directories. You’ll need to grant access to these directories explicitly. Credential stores like .ssh/.aws stay protected regardless.

Read approvals from `~/.claude/settings.json`

If you use Claude Code, safe-chains also honors the file-read approvals already in your ~/.claude/settings.json. A permissions.allow entry such as Read(//Users/you/.local/share/mise/**) or Read(~/.gem/**) becomes a read-only trusted directory — the same effect as a [[grant]] with read = true, so you don’t have to declare a directory in two places. Only absolute (//…) and home (~/…) paths are honored; a bare “read anything” rule is not (grant that explicitly in safe-chains.toml if you really want it). Edit(…)/Write(…) rules are deliberately not turned into write grants — reads only — and the credential shields and dotfile rule above still apply, so a broad read rule can’t reach .ssh. Only your user-level ~/.claude/settings.json is read, never a project’s .claude/settings.json.

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
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, since 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.

Auto-approval of reads and writes outside your project. File commands are checked by location, so cat ~/.ssh/id_rsa, cp secret /etc/x, and writes to system paths are not approved. See Files by location.

Auto-approval of writes to safe-chains’ own config. See Trusted directories.

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.

Trusted configuration

A project’s .safe-chains.toml must be trusted before safe-chains honors it. See Custom Commands.

What it does not prevent

Information disclosure inside your project: files in your project (and any trusted directories you grant) are readable, so cat .env sends their contents to the model provider. safe-chains gates by location, not by content; it won’t stop a read inside a directory you’ve allowed.
Filesystem confinement: safe-chains is NOT a sandbox. If you manually approve a dangerous command, safe-chains will not stop it. If you replace a safe binary with an evil binary, safe-chains will let it run. It only reads command strings, statically. For real confinement, pair it with an OS sandbox or the harness’s own file controls. safe-chains’ job is to auto-approve the safe commands so the prompts you DO get are meaningful.
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.

Best practices

Don’t run an agent from your home directory. safe-chains treats your working directory as the project, and files under it are read/write. From ~, a relative path like cat Documents/finances.csv is indistinguishable from a project file, so files throughout your home directory are exposed. Run agents from a project directory instead.

Grant narrowly. A trusted directory grant is a deliberate broad allow, the same broad access you get by running from a directory. Grant the specific directories you work in (~/projects), not all of ~.

Deny the folders you never want touched. On Claude Code, safe-chains only ever approves. It never denies, so a command it doesn’t recognize just falls through to Claude’s normal prompt. For a hard block on paths you never want touched, pair it with a second hook that denies them (Claude Code blocks the command if any hook denies it). A blunt backstop at ~/.claude/hooks/deny-paths.sh:

#!/bin/bash
cmd=$(jq -r '.tool_input.command // ""')
case "$cmd" in
  *.ssh/*|*.aws/*|*.gnupg/*|*/.env|*/secrets/*)
    jq -n '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:"protected path"}}' ;;
esac

"hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [
  { "type": "command", "command": "bash ~/.claude/hooks/deny-paths.sh" },
  { "type": "command", "command": "safe-chains" }
] } ] }

It’s a string match, not a parser: a safety net for the obvious cases while safe-chains does the rigorous allow-listing.

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