Documentation

Everything here assumes one thing happened first: you ran npx @crasp/cli setup inside a Claude Code project. That is the entire install.

Getting started

Requirements: Node.js 20 or newer. Nothing else — the CLI ships as a single dependency-free file.

$npx @crasp/cli setup

The first run shows npm's "Ok to proceed?" prompt and a short download. Setup then:

  • installs a self-contained copy to ~/.crasp/bin/crasp.js (shared by every project on the machine)
  • wires PreToolUse hooks for Write/Edit/Read/Bash and PostToolUse scanning for everything Claude reads — all by absolute path
  • adds the MCP server to .mcp.json, a git pre-commit hook, and a starter crasp.policy.yml
  • proves the installed hook blocks a synthetic secret — twice — before reporting success. If verification fails, setup exits non-zero and says exactly what to do.

Two things after it succeeds: restart any Claude Code session already open in the project (hooks load at session start), and approve the crasp MCP server when Claude Code prompts. Done — there is no step three.

Day-to-day commands

All optional — crasp runs by itself once wired.

crasp statusverify the install is healthy — checks every wired path and names the fix if one rotted
crasp panellive web dashboard of every decision across all your protected projects
crasp hook-logeverything crasp has intercepted; --summary for 30-day stats
crasp scan .scan the project right now; --severity high to filter
crasp check --stagedwhat the git pre-commit hook runs
crasp policy listevery active rule — built-in plus yours

Your own rules

Edit crasp.policy.yml in the project root. Your rules merge on top of the 55+ built-ins and can never weaken them.

id: my-policy
name: My Safety Policy
version: 0.1.0
rules:
  - id: no-prod-db
    description: Block any write mentioning the production database URL.
    severity: critical        # low | medium | high | critical
    target: any
    pattern: "prod\\.mycompany\\.com/db"
    message: "Production database reference detected."

critical rules deny the write outright; lower severities warn or ask. Run crasp policy list to see the merged result.

Exceptions & allowlists

Four escape hatches, narrowest first:

  • Inline: append # crasp:allow (or // crasp:allow) to any line to suppress secret findings on that line only.
  • Value allowlist: add known-safe strings or regex patterns under secrets.allowlist in the policy file.
  • Scan exceptions: files that legitimately quote rule patterns (docs, security guides, rule tests) trip check --staged and crasp scan — except them with the scan op. They're still scanned for secrets and always reported, never skipped silently.
  • Operation exceptions: pre-approve file access or a Bash command you run constantly:
exceptions:
  - path: "docs/**"
    ops: [scan]
    reason: "Docs quote rule patterns as examples"
  - path: ".env.local"
    ops: [read]
    reason: "Claude reads config during setup tasks"
  - command: "^rm -rf node_modules$"
    ops: [bash]
    reason: "Routine cleanup"

Command patterns are regexes matched against the whole command — anchor them (^…$) so a permissive pattern doesn't approve more than you intend. Scan globs resolve relative to the project root, and the scan op is always explicit — ops: [any] covers hook operations only.

Live dashboard

crasp panel — run it from any folder — opens a local web dashboard (127.0.0.1:4269) of crasp activity across all your protected projects, in four tabs. Overview: a verdict banner (All clear / Needs a look / Attention), today's checked/asked/blocked tiles, and an interactive chart — a range dropdown (Live · 10 · 15 · 30 · 45 · 60 · 90 days) sets the window, with per-day hover breakdowns. Activity: a flagged-first live feed that writes each event as a plain sentence and collapses routine clean runs. Rules: every rule that fired, with a plain-language name and a one-line explanation. Projects: per-project health cards and a copyable setup command. Live is a "from now" view — it counts only events after you switch to it — and events are logged whether or not the panel is open, so nothing is missed. Read-only and private: localhost-only, DNS-rebinding protected, zero external requests. --port and --no-open flags. Replaces crasp watch (removed in 0.2.2).

Scenario testing

Scenarios assert that your policy catches what it should — a YAML transcript with expectations, run with crasp run scenarios/<name>.yml. Setup writes three starters; expectation types are contains, not_contains and regex.

Updating

$npx @crasp/cli@latest setup

Run in any project: it replaces the one shared bundle at ~/.crasp/bin/crasp.js, so every project on the machine picks up the new version immediately. Always include @latest — a bare npx @crasp/cli setup may reuse a cached older copy. Re-running setup is also the universal repair: it migrates old hook formats and re-verifies everything.

Troubleshooting

crasp statusstart here. installHealth reports the exact problem — a deleted bundle, a Node version that was uninstalled, a legacy hook — and every problem carries its remediation (almost always: re-run setup)
hooks not firing?restart the Claude Code session — hooks load at session start, not mid-session
setup exited 1?that's the self-verification refusing to lie to you — the output names the failing stage and the fix

Removing crasp

In order — projects first, machine last:

  • per project: delete the crasp entries from .claude/settings.json and .mcp.json, remove the crasp block from CLAUDE.md, run crasp hook uninstall
  • then machine-wide: delete ~/.crasp/

Deleting ~/.crasp/ first leaves uncleaned projects with hooks pointing at a binary that no longer exists.