Sentnel

sentnel

A Claude Code `PreToolUse` hook that checks every tool call against a YAML rule file before it runs — and blocks the ones you've denied.

 

What it does

Claude Code lets you register hooks that run before each tool call. sentnel installs one Python script (`hook.py`) as a `PreToolUse` hook on all tools. Before Claude executes a `Bash` command, file read, or file write, the hook receives the tool call as JSON on stdin, matches it against a set of hardcoded static rules plus your editable `rules.yaml`, and either lets it through or exits with code 2 — which makes Claude Code block the call and show Claude the rule that fired. Every decision (allow and deny) is appended to a local SQLite database, so you get an audit trail of what your agent tried to do. No daemon, no network calls, no dependencies beyond Python 3 and PyYAML.

Claude Code
    │  tool call (JSON on stdin)
    ▼
sentnel hook.py  ── static rules, then rules.yaml (first match wins)
    │
    ├── allow (exit 0) ──▶ tool executes
    └── deny  (exit 2) ──▶ call blocked, Claude sees:
                           "Sentnel blocked this action — rule: "

Quickstart

One-liner (clones to `~/.sentnel` and registers the hook):

curl -sSL https://raw.githubusercontent.com/sentnelops/sentnel/main/setup.sh | bash

Or from a local clone ("sidecar mode" — the hook runs from wherever you cloned it):

git clone https://github.com/sentnelops/sentnel.git
cd sentnel
bash setup.sh

`setup.sh` does exactly this: installs `pyyaml` via `pip3`, creates `audit.db` (git-ignored), registers `python3 /hook.py` under `hooks.PreToolUse` in `~/.claude/settings.json` (idempotent — running it twice is safe), then runs a smoke test that pipes a fake `rm -rf` through the hook and verifies it exits 2.

A rule looks like this (from the shipped `rules.yaml`):