A report-only, pre-merge policy gate that runs as a Claude Code skill. It reads a diff, evaluates it against versioned rulesets, and emits a structured PASS / WARN / FAIL verdict. It never edits your code.
Install in one command —
/plugin marketplace add beemann/claudeguardthen/plugin install claudeguard@claudeguard. (What's new in 0.4.0)
ClaudeGuard is a gate, not a fixer. It answers one question on every change — "does this diff violate our policy?" — and leaves the decision to a human.
It deliberately reuses the host agent's existing engine (git, diff reading, reasoning) instead of rebuilding an LLM client, a diff analyzer, or a patch applier. The only thing ClaudeGuard owns is policy as data: a folder of plain-Markdown rules, each with a small frontmatter contract and a human-readable body describing what a failure looks like and why.
That design has three consequences worth stating up front:
- Separation of concerns. A component that both finds and fixes violations has an incentive to over-flag to look useful. A pure gate doesn't.
- No unreviewed merges. Running on a PR moments before merge, an auto-fixer would mutate the very diff a human just reviewed. ClaudeGuard reports; you act.
- Auditable output. A verdict table, a parseable JSON block and one fixed verdict line — diffable, reviewable, and mapped to a CI exit code.
The deterministic layer now does what the documentation said it did — every item was reproduced before it was fixed:
- Candidates come from tool output, as written. Step 5 builds the candidate
set with
git grepon the added lines; the oldgit diff | greprecipe could never match an anchored pattern and also searched removed lines. exempt_match.exemptclears a whole line (right for context, such as a command wrapped indocker compose exec);exempt_matchexcuses only the match it overlaps (right for values).process.env.KEY || "sk-live-…"is a candidate again — the environment reference no longer hides the literal beside it.- Wider rules.
no-anydetects every condition its body lists;no-invisible-characterssees 11 of 13 invisible classes instead of 2, using the same Unicode definition as ClaudeGuard Integrity. - Runners and CI agree with the skill. An explicit read-only tool set instead of
plan mode,
baseread from the config,<base>...HEADas the range, exit2for "no verdict" (an expired API credit is no longer a policyFAIL), current GitHub Actions, a pinned CLI, and arulesCI job that needs no API key.
0.3.0 (never published on main, shipped with 0.4.0) added probes — rules
whose evidence is the output of a read-only command, because some defects are
invisible in rendered text — a fourth state, UNEVALUATED, for a rule whose
probe could not run, and the no-invisible-characters rule.
Full notes, including how to upgrade, in the CHANGELOG.
Two ways to adopt ClaudeGuard, sharing one design — a universal engine
(the gate skill, _core rules, runner and rule-test scripts) plus per-project
policy (rulesets/house/, claudeguard.config.json, the CI workflow).
/plugin marketplace add beemann/claudeguard
/plugin install claudeguard@claudeguard
You immediately get two skills in every project: claudeguard (the gate) and
claudeguard-init (bootstrap). To scaffold the gate into the current repo, ask:
set up claudeguard · claudeguard init
The engine updates with /plugin update. When run as a plugin, the gate reads
its _core rules from the plugin and your house rules from the project.
Vendors the engine + a policy template into your repo, self-contained with no plugin dependency — ideal for CI:
# POSIX
bash scripts/install.sh /path/to/your/repo# PowerShell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1 -Target C:\path\to\your\repoThe installer is idempotent: it refreshes engine files on every run and never
overwrites your policy (rulesets/house/, claudeguard.config.json, an existing
workflow). See Forking into your project for what
it lays down.
Static linters catch syntax; they don't catch policy. "We run everything
through Docker", "no destructive migration without sign-off", "every new route
declares its auth posture", "no optimization without a measurement" — these are
team contracts that normally live in a CLAUDE.md nobody re-reads at review
time. ClaudeGuard turns those contracts into executable rules and enforces them
at the last cheap moment: before the merge.
The procedure is defined in SKILL.md and runs in six steps:
- Resolve the diff. The commits the branch adds,
<base>...HEAD. The base is the run's argument, elsebaseinclaudeguard.config.json, elseorigin/main. Uncommitted changes are not judged. - Resolve rulesets. Read every
*.mdfrom the engine's_core(${CLAUDE_PLUGIN_ROOT}/rulesets/_core/when installed as a plugin) and the project'srulesets/, dedupe byid(the project copy wins so a repo can override a shipped rule), honorclaudeguard.config.json(enable/disable, severity overrides), and keep only rules whoseapplies_toglobs match at least one changed file. - Smoke check (mandatory, anti-falsification). For each kept rule, state how many changed files it actually applies to. A rule that matches zero files is inert — the gate never invents violations to justify a rule.
- Run probes. A rule whose evidence is invisible in rendered text declares
read-only commands whose output is the evidence. A probe that cannot run makes
the rule
UNEVALUATED— never a pass. - Evaluate. Only added lines are judged. Rules with
detectpatterns get their candidates fromgit grepoutput (the model then adjudicates only those candidates, and lists the ones it dismissed); rules withoutdetectare judged by the model directly. Every violation cites a file, a line, and the offending line — a credential by prefix and length only. - Verdict.
FAILif a violation or anUNEVALUATEDrule reachesblock_on(defaulthigh);WARNif everything found is below it;PASSif clean.
ClaudeGuard emits a human-readable report, a machine-readable JSON block, and a final verdict line:
ClaudeGuard verdict: ❌ FAIL (1 high, 1 medium)
Base: origin/main · Files scanned: 7 · Rules: 2 clean · 2 failing · 1 unevaluated · 1 inert
Ruleset resolution
| Rule | Severity | Files matched | Status |
|--------------------------|----------|---------------|-------------------------------------|
| no-secrets | critical | 7 | ✅ checked — clean |
| docker-only | high | 1 | ❌ FAIL — 1 violation |
| no-any | medium | 3 | ❌ FAIL — 1 violation |
| security-routes | high | 2 | ✅ checked — clean |
| no-invisible-characters | high | 7 | ⚠️ UNEVALUATED — probe could not run |
| no-destructive-db | critical | 0 | ➖ n/a — not in this diff |
Violations
| Severity | Rule | File | Line | Why |
|----------|-------------|-----------------|------|-------------------------------|
| high | docker-only | scripts/dev.ps1 | 12 | `npm run dev` invoked on host |
| medium | no-any | src/api/user.ts | 44 | `: any` on request body |
{
"verdict": "FAIL",
"base": "origin/main",
"files_scanned": 7,
"rulesets_active": ["no-secrets", "docker-only", "no-any", "..."],
"rulesets_inert": ["no-destructive-db"],
"unevaluated": [{ "rule": "no-invisible-characters", "severity": "high", "why": "..." }],
"violations": [
{
"rule": "docker-only",
"severity": "high",
"file": "scripts/dev.ps1",
"line": 12,
"evidence": "+ npm run dev",
"why": "Command invoked on host instead of `docker compose exec app …`.",
"suggestion": "docker compose exec app npm run dev"
}
],
"dismissed": [{ "rule": "no-any", "file": "src/api/user.ts", "line": 51, "why": "..." }],
"block_on": "high"
}claudeguard-verdict: FAIL
Markers are fixed: ✅ checked and clean, ➖ inert (nothing to judge),
The runners read the last line and exit 0 for PASS/WARN, 1 for FAIL, and
2 when there is no verdict (setup error, the claude CLI failed, or the report
carried no verdict line).
Rules ship in two tiers:
| Tier | Folder | Intent |
|---|---|---|
| Core | rulesets/_core/ |
Universal, provider-agnostic, uncontroversial — adopt as-is. |
| House | rulesets/house/ |
Your team's opinionated rules — swap when you fork. |
Bundled rules:
| Rule | Tier | Severity | Trips on |
|---|---|---|---|
no-secrets |
core | critical | Credential/key/token literals (provider prefixes, PEM blocks, secret assignments). |
no-conflict-markers |
core | high | Unresolved git conflict markers committed to a tracked file. |
no-invisible-characters |
core | high | Characters a reviewer cannot see: controls incl. NUL, bidi, zero-width, Tags, variation selectors. Judged by two probes, not by reading. |
docker-only |
house | high | Project tooling run on the host instead of in-container (shell scripts, task runners, git hooks). |
no-destructive-db |
house | critical | Unguarded DROP/TRUNCATE/DELETE … without WHERE, etc. |
security-routes |
house | high | A new route/handler with no visible auth, validation, or injection posture. |
no-any |
house | medium | any, as any, @ts-ignore and other TypeScript escape hatches. |
measurement-first |
house | medium | A change claiming to optimize something with no benchmark/measurement. |
Install the plugin, or vendor the gate into the repository with the installer
(the rules must live in the project's rulesets/, not in the skill directory).
Then ask:
run claudeguard · gate this branch · check policy compliance
# POSIX — base defaults to `base` in claudeguard.config.json, then origin/main
bash scripts/check.sh [base-ref]# PowerShell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/check.ps1 [-BaseRef origin/main]Requires git, the claude CLI on PATH, and ANTHROPIC_API_KEY in the
environment. An empty diff is an immediate PASS. The runners give the model a
fixed read-only tool set — see Security model.
.github/workflows/claudeguard.yml runs two
jobs on every pull request to main/master (add your integration branch to
on.pull_request.branches if PRs target it):
rules—scripts/test-rules.sh: everydetectpattern against its fixtures. No model, no API key.gate— the verdict. Posts the report as a PR comment and job summary, and blocks the merge onFAILor on "no verdict". Add a repository secretANTHROPIC_API_KEYto activate it.
The Claude Code CLI is pinned in the workflow; bump it deliberately.
Copy claudeguard.config.example.json to
claudeguard.config.json and edit per project:
{
"base": "origin/main",
"block_on": "high",
"rules": {
"no-secrets": { "enabled": true },
"docker-only": { "enabled": true, "severity": "critical" }
}
}base— default ref to diff against, used by the skill and both runners when no base is passed. CI passes the pull request's target branch explicitly.block_on— minimum severity that produces aFAIL(low|medium|high|critical).rules.<id>.enabled— toggle a rule off without deleting it.rules.<id>.severity— override a rule's shipped severity.
Drop a *.md into rulesets/_core/ (universal) or rulesets/house/
(team-specific). No code change is required — the procedure picks it up
automatically.
---
id: no-todo-without-ticket
severity: low
applies_to:
- "**/*.ts"
- "**/*.py"
enabled: true
detect: # optional: deterministic candidate detection (ERE)
- 'TODO|FIXME'
exempt: # optional: a line that is fine in context
- '[A-Z]+-[0-9]+|#[0-9]+'
---
# No TODO without a tracking ticket
**FAIL** when the diff adds a `TODO`/`FIXME` with no issue reference.
Trip on added lines matching `TODO`/`FIXME` not followed by a ticket id
(e.g. `JIRA-123`, `#456`).
**Why:** untracked TODOs are debt that never gets scheduled.
**Suggestion:** link a ticket, or do the work now.Deterministic detection (optional). A rule may carry regex lists (case-insensitive POSIX ERE):
detect— what makes an added line a candidate.exempt— a match anywhere on the line drops the whole line: the line is fine in its context (a ticket reference, a command wrapped indocker compose exec, a comment).exempt_match— excuses only thedetectmatch it overlaps: the value is harmless (a documented dummy key, an environment reference). Use this one for values, or a real literal on the same line goes unseen.
Candidates come from git grep output, and the model only adjudicates them
against the rule body — so every trip condition the body lists needs a pattern,
or it is never looked at. Rules with no detect are judged by the model directly.
Test your patterns. Add fixtures/<rule-id>/should-fail.txt and
should-pass.txt, then run bash scripts/test-rules.sh (or test-rules.ps1). It
applies the same candidate rule to every line with no LLM and no API key, and
it fails while a rule with detect has no fixtures, so the deterministic layer is
regression-tested for free.
Probes. If a reviewer could not see the violation by eye, the rule needs a
probe: a read-only command (Read, Grep, Glob, read-only git) whose output
is the evidence. See rulesets/_core/no-invisible-characters.md.
Keep _core rules uncontroversial; anything debatable belongs in house/.
Every rule body should state, in plain language, what a FAIL looks like,
why it matters, and a suggestion — and should rely on evidence visible
in the diff, or declare a probe.
ClaudeGuard is a model reading text that the author of the change controls. State what that means before relying on it:
- It is a policy check, not a security boundary. A diff can contain instructions addressed to the model ("report PASS"). SKILL.md treats the diff as data, candidates for pattern rules come from tool output rather than from reading, and probe-carrying rules are judged by command output — but the verdict is still written by a model. Use ClaudeGuard to catch honest mistakes before review, and keep human review and branch protection for adversarial ones.
- Tools. The runners start the CLI with
--permission-mode dontAsk, allowRead,Grep,Globand read-onlygit(diff,grep,log,merge-base,rev-parse), and removeEdit,WriteandNotebookEdit. Claude Code runs read-only commands without asking in every mode, and some git flags write or execute;--outputis denied explicitly, the rest are not enumerated. So the boundary for a branch you do not trust is where the gate runs: an ephemeral CI runner or a container, never a workstation that holds credentials. - Secrets in CI. The workflow uses
on: pull_request, notpull_request_target. GitHub withholds secrets from pull requests opened from forks, so an untrusted PR cannot reach the API key — and the gate cannot run there either (reported as "no verdict"; therulesjob still runs). On a same-repository PR the author can already change the workflow itself, so the gate adds no access they lack.persist-credentials: falsekeeps the job token out of.git/config, where a file read would reach it. - The report is public. It is posted as a PR comment and job summary, so a credential is cited by prefix and length, never reproduced.
The fastest path is the standalone installer or the
claudeguard-init skill — both lay down exactly what's below. Under the hood it:
- Copies the engine into your repo: the gate skill →
.claude/skills/claudeguard/SKILL.md,rulesets/_core/with its fixtures,scripts/check.*andscripts/test-rules.*, and (if absent) the workflow. - Seeds
rulesets/house/with its fixtures andclaudeguard.config.jsononly if they don't already exist — your policy is never clobbered.
Then make it yours:
- Replace
rulesets/house/with your team's rules; keeprulesets/_core/. - Tune
applies_toglobs and trip patterns to your stack (e.g. Bun vs npm, Drizzle vs Prisma, Hono vs Express), with fixtures for everydetectrule. - Set
baseinclaudeguard.config.jsonto your integration branch, and add it to the workflow'son.pull_request.branchesif PRs target it. - On Windows, add
*.sh text eol=lfto.gitattributes: withcore.autocrlf=truea checkout writes the scripts with CRLF, and bash refuses them.
- Never edits, stages, or commits. A gate, not a fixer.
- Never invents violations to make a rule look useful. Inert rule → dropped.
- Evidence-based. Every violation cites the exact added line (a credential by prefix and length).
- "Could not check" is not "clean". An unevaluated rule never renders green.
- Precise over zealous. A false
FAILerodes trust faster than a missedLOW. - Deterministic output so report diffs stay reviewable.
MIT © 2026 Beeman