GouvernAI — Runtime Guardrails for Claude Code
Tiered risk governance for Claude Code: auto-approve what's safe, gate what's risky, deterministically hard-block what's dangerous, with a full audit trail.
Evidence shows layered least-privilege design (T1-T4 tiers, NEVER hard constraints, no credential exfiltration, anti-self-modification, fail-closed parsing, logs never contain secret values), MIT license, and candid threat-model disclosure of MCP bypass. Deducted because: the enforcement script guardrails-enforce.py itself was not provided in the reviewed files, so its behavior cannot be verified against claims; logging is silent by default (visible only via /guardrails log), reducing real-time transparency; publisher identity is unverified, leaving attribution incomplete.
Repo contains a substantial, well-structured hook test suite (regression tests, field-shape contracts, fail-closed cases); docs are self-consistent with explicit error handling. Deducted because: static review does not execute tests; the only CI workflow present is a version guard, not a test runner; README acknowledges a known upstream bug requiring manual /gouvernai activation of hooks, adding known deployment friction on a key path.
Trigger conditions, exclusion list, and non-fit ranges (MCP bypass, no PowerShell coverage, model-compliance variance) are clearly stated; the tier catalog is concrete. Deducted because: documentation is English-only with no Chinese-language support; scoped to Claude Code specifically with limited cross-platform and cross-model fit evidence.
Layered documentation (SKILL.md plus on-demand reference files) is a good progressive-disclosure example; MIT license, a version-guard CI keeping plugin./marketplace. in sync, complete install/uninstall instructions, and thorough limitation disclosure. Deducted because: no CHANGELOG, no explicit maintenance-ownership or update-commitment statement; publisher is an unverified individual account.
The problem is real (noisy default prompts vs. unsafe full bypass) and dual enforcement offers marginal value. Deducted because: static review cannot verify the claimed ~90% classification accuracy or ~60% auto-approval ratio (author assertions), screenshots are unverifiable, and core value requires runtime confirmation; silent logging may deprive some users of expected feedback.
Auditable primary material exists: full test suite, threat model, cited upstream issues and CVE context. Deducted because: no independent third-party execution evidence; the '120+ tests passing' badge is not corroborated by a test-running CI workflow; the ~60% and ~90% figures are unverifiable author claims.
- The enforcement script guardrails-enforce.py was not included in the reviewed files; audit the source before installing (the README itself advises this).
- A known Claude Code upstream bug may prevent hooks from auto-loading; /gouvernai must be run manually each session, otherwise only the probabilistic skill layer is active and the deterministic blocking layer is inert.
- MCP tool calls bypass the hook layer entirely; classification there is best-effort model behavior with no deterministic backstop.
- The audit log is silent by default; users must run /guardrails log to view entries — set expectations accordingly.
- Evasion vectors (variable staging from non-secret files, novel obfuscation, prompt injection) are explicitly out of scope per the author; pair with egress policies and secret vaults for defense in depth.
- Publisher identity is unverified; there is no CHANGELOG and update traceability relies on version numbers.
What does this skill do, and when should you use it?
GouvernAI is an MIT-licensed Claude Code plugin that solves the all-or-nothing permission problem — neither the interruption of default prompts nor the zero safety net of --dangerously-skip-permissions. It uses dual enforcement: a skill layer (SKILL.md plus ACTIONS/TIERS/POLICY reference files) lets the model apply judgment across T1–T4 risk tiers, while a hook layer (PreToolUse running guardrails-enforce.py) deterministically blocks obfuscated commands, credential exfiltration, and catastrophic operations even if the model skips the skill. All policy files are plain Markdown you can read and edit, and every gated action is appended to guardrails_log.md in the project root. It supports strict/relaxed/audit-only modes and token-cap cost governance.
Runs guardrails-enforce.py via PreToolUse hooks before every Bash/Write/Edit/Read call, detecting obfuscated commands, credential exfiltration (reading .env-style secret files then piping to curl/wget), rm -rf / and fork bombs, hardcoded API keys in file writes, and self-modification of guardrails files — exiting with code 2 (hard block) on violations and failing closed on unparseable input. The skill layer guides an 8-step gate: identify the action, read guardrails-mode. for mode, classify via ACTIONS.md, escalate via TIERS.md (bulk 5+ targets or unfamiliar recipients escalate +1 tier), check pre-approvals, check hard constraints via POLICY.md, apply controls, and silently append to guardrails_log.md. It also detects multi-step exfiltration patterns (variable staging then transmission, fragmented secret extraction, disguised health checks) and enforces a payload token cap (roughly 4 characters ≈ 1 token) set via /guardrails tokencap.
- Solo developers running Claude Code with --dangerously-skip-permissions for speed who want proportional safety restored without losing flow — the scenario where this plugin adds the most value
- Teams running CI, cron, or unattended tasks that need T2/T3 to auto-proceed but T4 to halt — switch to /guardrails audit mode
- Engineers worried about the model accidentally hardcoding API keys in generated files — the hook hard-blocks known key formats on file writes
- Team leads who need a consistent approval workflow and auditable policy files across sessions — mode config persists in guardrails-mode.
- Cost-sensitive heavy users who can set a token cap so oversized payload actions pause for approval like a T3 gate
What are this skill's strengths and limitations?
- Dual enforcement: the deterministic hook layer hard-blocks even if the model ignores the skill, and fails closed on unparseable input
- All policies are readable, editable Markdown — unlike Anthropic auto mode's opaque classifier
- Full audit log records tier, outcome, and escalation reason for every gated action — useful for team governance
- Supports strict/relaxed/audit-only modes and token caps, with 120+ passing hook unit tests and zero dependencies
- Honest threat-model documentation clearly delineates deterministic vs best-effort protections
- PreToolUse hooks cannot intercept MCP tool calls — MCP actions get only linguistic skill-layer governance with no deterministic backstop
- Due to a known Claude Code bug, hooks may not auto-load; you must run /gouvernai manually each session
- Skill-layer classification compliance is model-dependent — reliable (~90%) on Opus 4.6 / Sonnet 4.6, likely lower on smaller models like Haiku
- Hook patterns target Unix/Bash syntax; PowerShell equivalents aren't covered, and multi-step exfiltration with non-keyword variable names or fragmented extraction evades detection
- Hooks add ~10ms per tool call; token estimation is a rough 4-chars-per-token heuristic, not billing-accurate
- It's an operational safety and governance layer, not a security boundary — it cannot stop determined adversaries or novel obfuscation
How do you install this skill?
Run in your terminal: claude plugin marketplace add Myr-Aya/GouvernAI-claude-code-plugin, then claude plugin install gouvernai@mindxo (user scope by default, recommended; use --scope project only if you trust all contributors). Due to a known Claude Code bug where plugin hooks don't auto-load on some platforms, type /gouvernai at the start of each session to activate hooks; for stricter security, manually copy the hook config into ~/.claude/settings., replacing ${CLAUDE_PLUGIN_ROOT} with an absolute path.
How do you use this skill?
Run /gouvernai at session start to activate both enforcement layers. Most actions then pass silently; T2 (file writes, git commit) auto-approves with a brief notification; T3 (npm install, curl, email) pauses for approval; T4 (sudo, credential transmission, bulk deletes) requires approval after risk assessment. Use /guardrails for session stats, /guardrails strict or relaxed to switch modes, /guardrails audit for unattended runs, /guardrails tokencap <n> to set a token cap, and /guardrails log to view the audit trail. Modes persist across sessions via guardrails-mode..
How does this skill compare with similar options?
Versus Claude Code default prompts: the default interrupts every action equally, while GouvernAI adds friction proportional to risk. Versus Anthropic auto mode: auto mode's classifier is uninspectable and limited to Team/Enterprise plans, whereas GouvernAI's policies are transparent and editable on any plan, and its PreToolUse hooks run before the auto mode classifier. Versus --dangerously-skip-permissions: that mode offers zero safety net; GouvernAI restores proportional protection on top, where it adds the most value.