PromptGuard

PromptGuard audits prompts as behavioral contracts.

It is for agent workflows where vague prompts cause bad work, especially when an agent is about to edit files, seed system prompts, or ship code:

Fix this bug and write code.
Build this endpoint.
Give me the report.
Add this system prompt.

Think of it as a prompt linter for responsibility, safety, and execution contracts.

Most prompt advice says "write better prompts." PromptGuard turns that into an executable check:

• Is the task actually specified?
• Is the agent responsible for a clear surface?
• Are output format, constraints, risks, and verification explicit?
• Are safety boundaries contradicted later in the prompt?
• Should the agent ask for missing data instead of hallucinating a deliverable?

PromptGuard does not only say "bad prompt." It reports:

• what decision is missing
• what question to ask
• what contract is required
• what must be true before approval
• how to rewrite the prompt

What It Catches

• PG001 privacy conflicts
• PG002 unsafe/passive escalation
• PG003 agent boundary drift
• PG004 weak tool/function schema
• PG005 missing output contract
• PG007 vague deliverable intent
• PG008 later rule overriding earlier boundary
• PG009 long context without state retention
• PG010 false certainty without sources
• PG011 broad task without acceptance criteria
• PG012 coding prompt without responsibility
• PG013 recommendation without decision context
• PG014 high-stakes advice without safety/source contract
• PG015 technical change without risk/verification contract

Quick Start

Run without installing:

python3 -m promptguard audit prompts.py
printf '%s' 'Fix this bug and write code.' | python3 -m promptguard audit - --format markdown

Install as a local CLI:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
promptguard audit prompts.py

Install as an app with pipx:

pipx install promptguard
promptguard audit prompts.py

Install from GitHub before a package release:

pipx install "git+https://github.com/<owner>/promptguard.git"

Save reports:

promptguard audit prompts.py --format json --save

Saved reports go to:

.promptguard/reports.jsonl

Profiles, CI, and severity gates

# Coding-agent responsibility contracts only; fail CI on high+
promptguard audit task.md --profile coding-agent --fail-on high

# System / policy prompts
promptguard audit system.md --profile system --fail-on high

# Static security heuristics (PG016+)
promptguard audit agent.md --profile security --fail-on high

# Whole repo → SARIF for code scanning style review
promptguard audit-repo . --profile coding-agent --fail-on high --format sarif

# Intentional override trail
promptguard audit task.md --accept-risk PG012:deadline --apply-accepted --fail-on high

Profiles: general (default, all core rules), coding-agent, system, security.

--fail-on omitted keeps legacy behavior (any finding → exit 1). Use --fail-on none to always exit 0 after printing the report.

Baseline regression and promptfoo bridge:

promptguard audit task.md --profile coding-agent --save
promptguard audit task.md --profile coding-agent --baseline .promptguard/reports.jsonl --fail-on-new
promptguard export-promptfoo eval/cases.jsonl -o promptfooconfig.yaml

Rule packs may use word_any / regex_any fields for tighter matching; classic any substring fields stay compatible.

Out of scope for this release: interactive TUI, default LLM judge, runtime chat rails / red-team harnesses.

Agent-Native Guard

Install adapters:

./install-agent-adapters.sh codex
./install-agent-adapters.sh claude
./install-agent-adapters.sh opencode
./install-agent-adapters.sh openclaw

Restart the agent after install.

Behavior:

• prompt-like edits are audited before writing
• high/critical findings block write until explicit approval
• Codex/OpenCode get global AGENTS.md rules
• OpenClaw gets workspace AGENTS.md plus a before_tool_call plugin that blocks unsafe prompt writes
• Claude gets CLAUDE.md, optional hook config, and /prompt-audit
• The adapters copy the self-contained skills/promptguard bundle into each agent config/workspace directory, so the guard can run without a separate global CLI install.

Adapter status:

Installable Skill

The portable skill lives at:

skills/promptguard

Install from a skill installer by pointing to that path.

Examples

Bad:

Prod auth patlıyor galiba, refresh atınca bazı kullanıcılar düşüyor. Bi bakıp hızlıca fixler misin, akşama deploy lazım.

Expected findings:

• PG012 responsibility_contract
• PG015 technical_risk_contract

Better:

Act as the backend engineer responsible for src/auth/session.py and tests/auth. Fix the refresh-token logout bug only. Preserve public API behavior and do not refactor unrelated code. Validate expired token, reused-token, and concurrent-refresh edge cases. Verify with `pytest tests/auth -q`. Return changed files, root cause, verification output, deploy/rollback note, and residual risk.

Development

Run tests:

python3 -m pytest -q

Package smoke test:

tmpdir=$(mktemp -d /tmp/pg-package.XXXXXX)
python3 -m venv "$tmpdir/venv"
"$tmpdir/venv/bin/python" -m pip install -e .
printf '%s' 'Fix this bug and write code.' | "$tmpdir/venv/bin/promptguard" audit - --format table

Eval sets:

eval/cases.jsonl
eval/daily_life_cases.jsonl
eval/technical_cases.jsonl
eval/real_world_usage_cases.jsonl

More usage examples are in USAGE.md.

Real-world prompt examples are in EXAMPLES.md.

TUI design notes are in docs/TUI.md.

Part of mturac/tools

This project is part of an open-source toolkit for AI-augmented engineering — Claude Code plugins, MCP servers, security scanners, schedulers, and dev-productivity utilities. See the hub for the full list.

Install every Claude Code plugin from one place:

/plugin marketplace add mturac/claude-plugin-marketplace
/plugin install promptguard