safe-chains 0.55.1

Auto-allow safe, read-only bash commands in agentic coding tools
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

# `safe-chains`

A command safety checker that auto-allows safe, read-only bash commands without prompting. Works as a Claude Code pre-hook, a CLI tool, or an OpenCode plugin.

When an agentic tool wants to run a bash command, safe-chains checks if every segment of the command is safe. If so, the command runs without asking for permission. If any segment is unsafe, the normal permission flow takes over. Commands in piped chains, `&&`, and `;` sequences are each validated independently.

For chained commands, safe-chains also reads your Claude Code settings to approve segments you've already permanently approved but that Claude Code can't match because the command contains shell operators. See [Settings-aware chain approval](#settings-aware-chain-approval).

See [COMMANDS.md](COMMANDS.md) for the full list of supported commands.

## Install

### Homebrew (macOS)

```bash
brew install michaeldhopkins/tap/safe-chains
```

This installs the binary, man page, shell completions, and the OpenCode plugin. If Claude Code is detected (`~/.claude` exists), the hook is automatically configured. If OpenCode is detected, setup instructions are printed.

### Pre-built binary

Download signed, notarized binaries from [GitHub Releases](https://github.com/michaeldhopkins/safe-chains/releases/latest). Available for macOS (Apple Silicon and Intel) and Linux (x86_64 and aarch64).

```bash
# Example for macOS Apple Silicon:
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/   # or anywhere in your PATH
```

### With Cargo

Requires [Rust](https://rustup.rs/).

```bash
cargo install safe-chains
```

### From source

```bash
git clone git@github.com:michaeldhopkins/safe-chains.git
cd safe-chains
cargo install --path .
```

## Configure

### Claude Code

If you installed via Homebrew, the hook is already configured. Otherwise, add this to `~/.claude/settings.json`:

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

Restart your Claude Code sessions to activate the hook. Once configured, updating the `safe-chains` binary takes effect immediately.

### OpenCode

If you installed via Homebrew, the plugin is available at `$(brew --prefix)/share/safe-chains/opencode-plugin.js`. Copy it to your project:

```bash
mkdir -p .opencode/plugins
cp $(brew --prefix)/share/safe-chains/opencode-plugin.js .opencode/plugins/
```

If you installed via cargo or from source, copy `opencode-plugin.js` from the repository to `.opencode/plugins/` in your project.

The plugin intercepts bash commands before OpenCode executes them. Safe commands run without prompting; unsafe commands are blocked and OpenCode's normal permission flow takes over.

Requires `safe-chains` in PATH.

## Usage

### Claude Code (hook mode)

With the hook configured above, 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.

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

## How it works

### Built-in rules

safe-chains knows 130+ read-only commands (`grep`, `cat`, `ls`, `jq`, ...) that are always safe with any arguments. For 50+ additional tools (`git`, `cargo`, `npm`, `docker`, ...), it validates specific subcommands and flags—allowing `git log` but not `git push`, allowing `sed 's/foo/bar/'` but not `sed -i`.

Commands containing shell operators (`&&`, `|`, `;`) are split into segments. Shell compound commands (`for`/`while`/`until` loops and `if`/`elif`/`else` conditionals) are parsed into an AST and each leaf command is validated recursively, supporting arbitrary nesting depth. Simple segments are validated independently. Segments containing output redirection (`>`), input redirection (`<`), backticks, or command substitution (`$(...)`) are always rejected.

Found a safe command safe-chains should support? [Submit an issue.](https://github.com/michaeldhopkins/safe-chains/issues/new?template=command-request.yml)

### Settings-aware chain approval

`safe-chains` lets you significantly tighten up your approved bash commands and also makes your remaining allowed commands more useful. When a chain doesn't fully pass built-in rules, safe-chains reads your Claude Code settings and checks each segment independently against your approved patterns. 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

All segments covered, so the chain is auto-approved. If any segment fails both checks, safe-chains makes no decision and Claude Code prompts as usual.

**Settings files read:**

| File | Source |
|------|--------|
| `~/.claude/settings.json` | Global settings |
| `$CLAUDE_PROJECT_DIR/.claude/settings.json` | Project settings |
| `$CLAUDE_PROJECT_DIR/.claude/settings.local.json` | Local project settings (gitignored) |

### Guardrails

Segments with `>`, `<`, `` ` ``, or `$(...)` outside of quotes are never approved via settings, even if a pattern matches. This prevents `Bash(./script *)` from approving `./script > /etc/passwd`.

Glob patterns are matched per-segment. A pattern matching one segment cannot cause another segment in the chain to be approved.

Missing, unreadable, or malformed settings files are silently skipped—fewer patterns means more conservative behavior.

Broad patterns like `Bash(bash *)` will approve nested commands without recursive validation. If you have `Bash(bash *)` in your settings and a segment is `bash -c "safe-cmd && evil-cmd"`, the settings match takes precedence over the built-in shell handler's recursive check. This matches Claude Code's own behavior for approved patterns.

When matching allowed commands from settings, `safe-chains` splits first, then matches each segment in isolation, so `*`/`:*` doesn't leak.

### Tip: prefer CLI tools over Python

With compound command support, most commands that trigger approval prompts will be `python3` invocations. Consider instructing Claude to prefer safe CLI tools (`jq`, `grep`, `awk`, `sed`, `sort`, `curl`, etc.) over `python3` for data processing. Add something like this to your project's `CLAUDE.md`:

```
Prefer CLI tools (jq, grep, awk, sed, sort, curl) over python3 for data processing.
```

This reduces approval prompts without weakening security—when `python3` does come up for approval, it's more likely to be something worth paying attention to.

## Developing

```bash
cargo test
cargo clippy -- -D warnings
```

Adding a new command:

1. Add constants and handler function in the appropriate `src/handlers/` module
2. Register it in the dispatch match in `src/handlers/mod.rs`
3. Add `#[cfg(test)]` tests in the handler module covering both allow and deny cases
4. Run `cargo test` and `cargo clippy -- -D warnings`
5. Run `./generate-docs.sh` to regenerate COMMANDS.md
6. Run `cargo install --path .` to update the installed binary

---

Copyright 2026 Michael Hopkins