Metadata-Version: 2.4
Name: prompt-guardian
Version: 0.1.1
Summary: Token risk analysis and audit logging for Claude Code via native hooks
Project-URL: Repository, https://github.com/jsharma103/prompt_guardian
Author-email: Jay Sharma <jsharma3962@gmail.com>
License: MIT
Keywords: ai,audit,claude,claude-code,hooks,security
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: anthropic>=0.40.0
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# Prompt Guardian

Token risk analysis and audit logging for [Claude Code](https://claude.ai/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

```bash
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 | bash` |
| 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:

```bash
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

```bash
# 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

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

---

## Configuration

`~/.guardian/config.json`:

```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
