Offline prompt linter for Claude Code and Codex

Prompt contracts for agent workflows.
Offline · deterministic · zero dependencies

---

Agents do what you ask — even when what you ask is incomplete.

Fix this bug and write code.

PromptGuard treats that line as a contract, not a wish. It checks whether role, surface, constraints, verification, and safety are explicit enough to execute — and stops vague instructions before they become a bad write.

printf '%s' 'Fix this bug and write code.' \
  | promptguard audit - --profile coding-agent --fail-on high

---

Install

pipx install "git+https://github.com/mturac/promptguard.git"
# or: pip install -e .

promptguard audit path/to/prompt.md --profile coding-agent --fail-on high

---

What you get

Findings	Evidence, impact, missing contract, questions, approval criteria
Fix draft	Rewrite that keeps your wording and fills the gaps
Profiles	coding-agent · system · security · general
CI	Severity gates, repo walk, SARIF, baseline diffs
Agents	Pre-write guard for Hermes, Claude, Codex, OpenCode, OpenClaw

No model calls. No network. Safe in hooks and air-gapped machines.

---

Profiles

promptguard audit task.md   --profile coding-agent --fail-on high
promptguard audit system.md --profile system       --fail-on high
promptguard audit agent.md  --profile security     --fail-on high

Profile	When
coding-agent	Implementation prompts — ownership, scope, verification
system	System / router / policy text — safety and precedence
security	Instruction hardening — override and exfil patterns
general	Full core catalog (default)

--fail-on high fails only on high or critical. Omit it to fail on any finding. Use --fail-on none to report without failing.

---

CI

promptguard audit-repo . --profile coding-agent --fail-on high --format sarif
promptguard audit task.md --baseline .promptguard/reports.jsonl --fail-on-new

Walk prompt-like files, export SARIF, or gate on new findings only. Save history with --save → .promptguard/reports.jsonl.

promptguard audit task.md --accept-risk PG012:deadline --apply-accepted

---

Agents

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

Restart after install. Hard-block plugins honor:

export PROMPTGUARD_PROFILE=coding-agent
export PROMPTGUARD_FAIL_ON=high

Hermes	Skill + pre_tool_call plugin · /promptguard
OpenClaw	Skill + before_tool_call plugin
Claude	Skill + CLAUDE.md · optional hook
Codex / OpenCode	Skill + AGENTS.md

Hermes

./install-agent-adapters.sh hermes
# or skill only from this repo:
hermes skills install mturac/promptguard/skills/promptguard

Uses the active profile home from hermes config path. Chat: /promptguard. Plugin blocks prompt-like write_file / patch / edit. Off: PROMPTGUARD_HERMES_DISABLE=1.

---

Review

promptguard tui task.md --profile coding-agent

Navigate findings, open a fix draft, record accept-risk, save. Non-interactive environments get a table and a non-zero exit on high+ findings.

---

Example

Vague

Prod auth patlıyor, refresh’te kullanıcı düşüyor. Hızlıca fixler misin, akşama deploy.

→ typically PG012 and PG015.

Contracted

Act as the backend engineer for src/auth/session.py and tests/auth.
Fix the refresh-token logout bug only; preserve public API behavior.
Verify with `pytest tests/auth -q`.
Return changed files, root cause, verification output, and residual risk.

---

Rules (selection)

ID	Concern
PG012	Coding without ownership / surface / verification
PG015	Technical change without risk / rollback / tests
PG008	Later exception weakens an earlier hard boundary
PG004	Tool call without a real schema
PG016–018	Security pack: override, leak, exfil

Full catalog and fixtures: eval/ · USAGE.md

---

Develop

python3 -m pytest -q

USAGE.md · EXAMPLES.md · CHANGELOG.md

---

_{Part of mturac/tools}