saferead 2026.6

Claude Code PreToolUse hook that auto-approves known-safe read-only shell commands.

saferead

A Claude Code PreToolUse hook that auto-approves known-safe, read-only shell commands — so routine reads (ls, cat, git status, grep, …) don't interrupt you with permission prompts.

What it does

saferead inspects each Bash command Claude Code is about to run and returns one of three verdicts:

• allow — every part of the command is a recognized read-only operation.
• ask — a gated git write (add / commit / stash) on a protected branch (master / main); you get a confirmation prompt.
• abstain — anything it doesn't recognize: it stays silent and lets Claude Code's normal permission flow proceed.

It never denies a command. It only ever removes friction (allow) or adds a confirmation (ask), so it composes safely alongside any separate command-blocking layer you run.

Compound commands are decomposed at top-level &&, ||, ;, |, and newlines (quote / backtick / $(…)-aware). A command is allowed only when every segment is a recognized safe read.

Design guarantee

The cardinal rule is zero false-allows: a command that mutates state must never be silently approved. Coverage is secondary — when in doubt, it abstains. The hook is also built to never crash or block Claude Code: any internal error is caught and the hook abstains.

Examples

Command	Verdict	Why
ls -la, cat README.md, grep -rn foo src	allow	read-only
git status, git log --oneline, git diff	allow	read-only git
cat a.txt && wc -l a.txt	allow	every segment is a safe read
git commit -m "wip" on main	ask	gated write on a protected branch
git add . on a feature branch	allow	gated write off a protected branch
rm -rf build	abstain	not recognized → normal prompt
npm install	abstain	not a read
cat a.txt && rm b.txt	abstain	one segment mutates state

Only the Bash tool is inspected; every other tool is left untouched.

Install

One command — with uv installed — sets up saferead and registers it as a Claude Code hook:

uvx saferead install

This installs saferead permanently (via uv tool install) and writes a PreToolUse entry (matcher Bash) whose command is the full path to the installed saferead binary — a direct exec on the hot path, with no launcher overhead. The target settings.json is backed up first and any existing hook entries are left untouched; re-running is idempotent.

It prompts whether to install to the global ~/.claude/settings.json or the current project's .claude/settings.json. Pass a modifier to skip the prompt (for scripted / non-interactive installs):

uvx saferead install --project               # install into ./.claude/settings.json
uvx saferead install /path/to/settings.json  # install into an explicit path

The entry looks like:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [ { "type": "command", "command": "/home/you/.local/bin/saferead" } ] }
    ]
  }
}

Configuration

Configuration is optional — saferead ships with safe built-in defaults. Two TOML files are read, both optional:

File	Trust	Purpose
~/.config/saferead/config.toml	trusted	your global settings
$CLAUDE_PROJECT_DIR/.claude/saferead.toml	untrusted	per-project overrides

The project file can only narrow trust (add protected branches, disable recognizers) — it can never broaden the allow-set for git writes, by design.

Every key is optional; the values below are the built-in defaults:

[git]
protected_branches = ["master", "main"]           # ask on a gated git write on these branches
gated_subcommands  = ["add", "commit", "stash"]    # which git writes are gated

[recognizers]
disabled = []   # recognizer tags to turn off (those commands then abstain)

[python]
allowed_modules = ["math", "datetime", "json"]  # modules the `python -c` analyzer admits
allowed_methods = []                            # extra read-only methods to admit

[read]
local_allowed_roots = []   # empty = allow any path; non-empty restricts file reads to these roots
ssh_allowed_roots   = []

[logging]
enabled = true                       # audit log of every allow/ask decision (ON by default)
path = "/tmp/claude-hook-audit.log"  # where that audit log is written

Logs

saferead writes two files under /tmp:

• Audit log (/tmp/claude-hook-audit.log) — one JSON line per allow/ask decision. On by default; configure or disable it via the [logging] table above.
• Error log (/tmp/claude-hook.log) — internal diagnostics if the hook ever hits an error (it always abstains rather than crashing). Fixed path, not configurable.

Updating

Re-run the same command:

uvx saferead install

This upgrades saferead to the latest version and refreshes the hook entry.

Changelog

See CHANGELOG.md or the GitHub Releases page.

License

GPL-3.0-or-later