prompt-guardian 0.1.0

Token risk analysis and audit logging for Claude Code via native hooks

Prompt Guardian

Token risk analysis and audit logging for Claude Code via native hooks.

Guardian monitors every prompt and tool call in your Claude Code sessions, classifies risk using heuristic patterns and the Claude API, warns you before dangerous actions, and logs everything to a local SQLite database.

---

Install

pip install prompt-guardian
guardian install        # register hooks globally (~/.claude/settings.json)
guardian install --project  # or project-level (.claude/settings.json)

After installing, restart Claude Code. Guardian runs automatically on every session.

---

How it works

Guardian hooks into six Claude Code events:

• UserPromptSubmit — classifies your prompt and injects a warning into Claude's context if risk is medium or above. Claude surfaces this warning at the start of its response.
• PreToolUse — classifies tool inputs (Bash, Write, Edit) before execution
• PostToolUse / PostToolUseFailure — logs success, duration, and failure reasons
• Stop — finalizes the turn with actual token counts

Guardian never blocks your workflow. It warns and logs — that's it.

---

Risk levels

Level	Examples
critical	rm -rf, drop table, mkfs, `curl
high	credential exposure, git push --force, npm publish
medium	sudo, git push, docker run, kubectl, terraform apply
low	everything else

By default, guardian uses heuristic regex patterns for speed. Enable API classification (Claude Haiku) for more accurate results on medium+ prompts:

guardian config set-key   # stores your Anthropic API key in ~/.guardian/config.json

Then set api_analysis.enabled: true in ~/.guardian/config.json.

---

CLI commands

# Installation
guardian install [--project]     # register hooks
guardian uninstall [--project]   # remove hooks
guardian status                  # check registration + DB stats

# Reporting
guardian report [--limit N] [--risk LEVEL] [--since DURATION] [--session] [--current-session]
guardian top [--limit N]         # top N prompts by token usage
guardian stats                   # aggregate counts by risk, action, tool, project
guardian patterns                # which heuristic patterns have fired most
guardian false-positives         # where heuristic over-classified vs API

# Management
guardian clear                   # wipe all history (with confirmation)
guardian config set-key          # set Anthropic API key interactively

Examples

guardian report --risk medium --since 7d
guardian report --current-session
guardian top --limit 5
guardian patterns

---

Configuration

~/.guardian/config.json:

{
  "api_key": "sk-ant-...",
  "api_analysis": {
    "enabled": true,
    "always_api": false,
    "timeout_seconds": 5,
    "model": "claude-haiku-4-5-20251001"
  },
  "auto_approve_tools": ["npm test", "npm run lint", "git status"],
  "log_prompt_previews": true
}

---

Data

All data is stored locally at ~/.guardian/history.sqlite. Nothing is sent anywhere (except prompts to the Anthropic API for classification, if enabled).

---

License

MIT