claude-code-guardrails
CLAUDE.md32 starsChanged 3 months agoMITView on GitHub
Public plugin repo. Read this before changing anything; the README covers what the files do. This file lives in .claude/ on purpose: Claude Code loads it for checkouts of this repo, while a root-level CLAUDE.md is not loaded for plugin users and trips claude plugin validate --strict. - The maintainer's private ~/.claude config is the canonical source. This repo is a curated, scrubbed downstream of it: hooks/git-staging-guard.sh, precompact-handoff.sh, session-start.sh (private name: session-start-hook.sh), format-file.sh, scripts/sync-commands.sh, commands/ (except setup-check.md), skills/browser-mcp/, output-styles/terse.md and…
In this repositoryOne other file it gives its agents.
- browser-mcpSkill
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
Never add hostnames, IPs, client or product names, SSH aliases, or home-directory absolute paths.
- Very specific: line 55
Never put $ followed by a digit inside a shell block in a commands/*.md file: the harness substitutes positional arguments there before the …
≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
claude-code-guardrails
Public plugin repo. Read this before changing anything; the README covers what the files do.
This file lives in .claude/ on purpose: Claude Code loads it for checkouts of this repo, while a
root-level CLAUDE.md is not loaded for plugin users and trips claude plugin validate --strict.
Where changes come from
- The maintainer's private
~/.claudeconfig is the canonical source. This repo is a curated, scrubbed downstream of it:hooks/git-staging-guard.sh,precompact-handoff.sh,session-start.sh(private name:session-start-hook.sh),format-file.sh,scripts/sync-commands.sh,commands/(exceptsetup-check.md),skills/browser-mcp/,output-styles/terse.mdanddocs/have a private twin. The skill is a rewrite: port lessons, never the sites or setup. Public-only:sql-guard.sh,hooks.json, the manifests,tests/, CI, README, the reviewer adapter (scripts/review-backend.sh, its.conf.example, the findings schema) and/setup-check(commands/setup-check.md,scripts/setup-check.sh,docs/setup-check.md). commands/critical-review.mdis a port, not a copy: the private twin stays pinned to the Codex plugin by design, the public one callsscripts/review-backend.sh. Port review-logic changes (scope, brief, filtering, findings format) in both directions; do not port the backend abstraction back unless the maintainer says so.- Improvements to a file with a private twin are ported in both directions on purpose — a drift check on the private side flags when either side moved. Fix here freely, but say in the commit message what needs porting back.
- The two copies differ deliberately: no hostnames, client names, private tooling references or absolute paths here. Do not "restore" anything that looks stripped.
Gates before a commit
bats tests/green (bats-core; CI runs the same suite on ubuntu). A hook change without a test change is suspicious. Under bash 3.2 a failing[[ … ]]that is not a test's last line does NOT fail the test — only bash ≥ 4.1 (CI) enforces it; use[ … ]for exact matches.- The maintainer's scrub grep (term list is private, ask for it to be run) must return nothing. Never add hostnames, IPs, client or product names, SSH aliases, or home-directory absolute paths.
claude plugin validate --strict .claude-plugin/plugin.jsonandclaude plugin tag .must pass;plugin.jsonandmarketplace.jsonversions must agree. Tags areguardrails--vX.Y.Z.
Conventions the code cannot show
- Target is bash 3.2 (macOS default): no associative arrays, no
${var,,}, nomapfile; underset -uan empty array is "unbound", so expand optional argv as${arr[@]+"${arr[@]}"}. Dependencies stay at bash, git, python3. - Under
pipefail, neverproducer | grep -q: grep exits on the first match, the producer dies of SIGPIPE on large input and the match reads as a miss. Grep the file directly, or match in bash. - Hook exit codes: only exit 2 blocks a tool call and shows stderr to the model; exit 1 is a non-blocking notice and the call proceeds. Tests assert the code, not the message.
- Any PreToolUse (Bash) hook fires on every Bash call. It must gate on a pure-bash
caseprefilter and spawn python3 only when the payload can match. Measured numbers indocs/git-staging-safety.md. - Hooks are habit guards, not sandboxes: they inspect text. Accept documented residuals rather than growing regexes into a parser.
hooks.jsonreferences scripts viabash "${CLAUDE_PLUGIN_ROOT}/hooks/<name>.sh"; never an absolute path.- Never put
$followed by a digit inside a shell block in acommands/*.mdfile: the harness substitutes positional arguments there before the model sees it. Uselength(),NF, sed groups. - Commands must degrade explicitly when an optional dependency is absent (
--codexwithout the Codex plugin,--uiwithout a browser MCP): say so and continue, never pretend. commands/verify.mdandcommands/critical-review.mdread the session files${TMPDIR:-/tmp}/claude-session-start-{commit,dirty,blobs}-${CLAUDE_SESSION_ID}written byhooks/session-start.sh; keep the three in sync.${CLAUDE_SESSION_ID}and${CLAUDE_PLUGIN_ROOT}are substituted into command text by the harness — they are NOT environment variables inside Bash calls, so pass them as arguments to anything that needs them.scripts/review-backend.shis the only vendor-specific file: it must never take the brief or any intent as input, never run a backend other than the one named, and never exit 0 without a review. Backend tests use fakecodex/claudeexecutables on PATH — no model calls intests/. Design decisions, CLI gotchas and measured timings:docs/review-backend.md.
Testing a change like a user
CLAUDE_CONFIG_DIR=$(mktemp -d) claude plugin marketplace add "$PWD"
CLAUDE_CONFIG_DIR=<same dir> claude plugin install guardrails@tillmeier
CLAUDE_CONFIG_DIR=<same dir> claude plugin details guardrails # component inventory + token costWorks pre-publication from the local path and without a login. A model-in-the-loop run in a fresh profile needs a login there; the SessionStart hook fires before that gate and proves the wiring.
Writing
Plain and to the point: what a thing does, how, how to use it. No self-promotion, no story
sections in README or manifests; incident write-ups and measurements live in docs/.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

