Guardrails for AI coding assistants. Intercepts mistakes — billing loops, duplicate files, type safety bypasses, code standard violations — before they cost you time.
Works with Claude Code, OpenCode, Cline, Cursor, Kilo Code, and Factory Droid.
npm install -g ai-guard-pluginsThen run the installer for your platform:
ai-guard-install # auto-detects your tool
ai-guard-install --platform opencode
ai-guard-install --platform claude
ai-guard-install --platform cline
ai-guard-install --platform cursor
ai-guard-install --platform kilo
ai-guard-install --platform factoryFor Factory Droid, hooks merge into ~/.factory/settings.json using the nested hooks format from the Factory hooks guide (absolute bash paths, Create|Edit matchers for file tools, optional timeout). A copy-paste template lives at templates/factory-settings-ai-guard.fragment.json.
curl -fsSL https://raw.githubusercontent.com/YosefHayim/ai-guard-plugins/main/install.sh -o /tmp/ai-guard-install.sh
bash /tmp/ai-guard-install.sh
# Or specify platform explicitly
AI_GUARD_PLATFORM=opencode bash /tmp/ai-guard-install.sh
AI_GUARD_PLATFORM=factory bash /tmp/ai-guard-install.sh| Command | What it proves |
|---|---|
npm test |
Host: Gemini + Cursor + Claude + Factory contracts; requires bash, jq, and python3 (Factory settings merge tests). |
npm run test:docker |
Clean Debian bookworm image (Dockerfile.verify): npm install + global gemini CLI + full npm test. |
npm run test:docker:ubuntu |
Clean Ubuntu 24.04 image (Dockerfile.verify.ubuntu): Node 22 from NodeSource + same test suite. |
npm run verify:containers |
Runs both Docker builds back-to-back (Debian then Ubuntu). |
CI (when this repo is on GitHub): Docker verify workflow builds both Linux Dockerfiles; Cross-platform verify runs npm test on ubuntu-latest, macos-latest, and windows-latest (jobs use bash, install jq per OS, and Python 3.12 for merge-script tests). On Windows, automation uses Chocolatey jq and the default bash shell — align local dev with Git Bash or WSL if you run hooks by hand.
AI coding assistants are powerful but reckless. Without guardrails they will:
| Problem | What happens | Time wasted |
|---|---|---|
| Billing error retry loop | Agent retries a failed API call that will never succeed | 10-15 min |
| Huge paste burns context | 50K-char log dump eats your entire context window | Session ruined |
| Duplicate file creation | Agent creates utils/format-date.ts when utils/dates.ts already exists |
5-10 min cleanup |
| Duplicate functions/types | Agent re-implements getErrorMessage() or UserRow that already exist elsewhere |
5-15 min cleanup |
| Type errors left behind | Agent edits a file, introduces type errors, moves on to next task | 5-20 min debugging |
as any to "fix" types |
Agent suppresses type errors instead of solving them | Tech debt |
| Placeholder code | // TODO: implement later — it never does |
Manual rework |
| No memory across sessions | Same mistakes repeated every time | Ongoing |
ai-guard-plugins intercepts these at runtime — blocking, warning, or learning — so you don't babysit.
Detects billing/payment errors in API responses and stops the agent immediately. No more infinite retry loops burning tokens on a problem that requires human action.
Before creating any new file, searches for similar filenames, existing files in the target directory, and symbol collisions. Warns the agent to extend existing code instead. If the target path already exists (edits, overwrites), checks are skipped — runtime hooks and hooks/dry-guard.sh exit early so you are not nagged on every save.
Function & type-level duplication detection. Session start rebuilds an index of functions/types across the repo; each edit runs dedup-check-file on only that file’s symbols vs. the rest of the codebase (this is not the full-repo DEDUP-REPORT.md from ai-guard-dedup / dedup-full-scan.ts). Flags same names elsewhere, ≥80% body/field similarity, and fuzzy names when .dedup.json thresholds are met. Claude Code PostToolUse blocks the edit by default when duplicates are found; set AI_GUARD_DEDUP_BLOCK=0 for warn-only. Cursor uses afterFileEdit + dedup-violations.md (soft block via rules). Gemini CLI uses AfterTool (.gemini/hooks/dedup-after-write.sh) to deny the tool result when duplicates are found. Standalone: npx tsx plugins/dedup-check-file.ts <file>.
Runs tsc --noEmit after every .ts/.tsx edit and reports type errors back to the agent. Auto-detects the project's tsconfig (tsconfig.src.json → tsconfig.app.json → tsconfig.json). The agent must fix all errors before proceeding. On by default; set AI_GUARD_TYPECHECK=0 to disable (e.g. huge monorepos).
Blocks as any, @ts-ignore, require(), TODO/FIXME placeholders, underscore naming, and logic in index files. Every write/edit is checked.
Runs biome check --fix --unsafe automatically after every file write. No more commit-time lint failures. Requires Biome.
When input exceeds 10K characters, auto-summarizes while preserving all code, paths, and error messages verbatim. Requires an Anthropic API key.
Tracks recurring anti-patterns (DRY violations, type bypasses, scope creep, security issues) across sessions. Logs to persistent JSONL. The more you use it, the smarter it gets.
Samples local session files only (no HTML exporters): Cursor agent-transcripts .jsonl, Claude Code ~/.claude/projects session *.jsonl / *.json, and OpenCode storage. Builds a text bundle, calls OpenAI, Gemini, or Ollama, and writes a draft Markdown report. Implements insights-seen deduplication so reruns skip already-processed session paths.
After npm install -g ai-guard-plugins, run from any project that has a .cursor folder (so repo root and .env resolve):
cd /path/to/your/repo
npm run cursor-transcript-insights --prefix "$(npm root -g)/ai-guard-plugins" -- --dry-run --max-sessions=5 --sources=allOr from a git clone of this repo:
cd /Applications/Github/ai-guard-plugins
npm run cursor-transcript-insights -- --sources=all --max-sessions=40
# Optional: npx tsx path (same flags)
npm run cursor-transcript-insights-tsx -- --sources=allUse --sources=cursor|claude|opencode|all, GEMINI_API_KEY / GOOGLE_API_KEY, or OPENAI_API_KEY. See .cursor/rules/agent-transcript-pipeline.mdc for flags and env vars.
| Platform | Format | Enforcement | Install location |
|---|---|---|---|
| OpenCode | TypeScript plugins | Runtime — blocks violations | ~/.config/opencode/plugins/ |
| Claude Code | TypeScript plugins | Runtime — blocks violations | ~/.claude/plugins/ |
| Cline | Bash hooks | Runtime — cancels via JSON contract | ~/.clinerules/hooks/ |
| Cursor | .mdc rules |
Advisory — AI follows as instructions | .cursor/rules/ |
| Kilo Code | .md rules |
Advisory — AI follows as instructions | .kilo/rules/ |
| Factory Droid | settings.json hooks |
Runtime — same bash hooks as Claude (stdin JSON) | ~/.factory/settings.json |
Runtime = programmatic interception that can block operations. Advisory = rules injected into the AI's system prompt as guidelines.
# OpenCode
cp plugins/*.ts ~/.config/opencode/plugins/
# Claude Code
cp plugins/*.ts ~/.claude/plugins/Optional global PreToolUse hook (same DRY logic, JSON stdin/stdout contract some setups use under ~/.claude/hooks/):
cp hooks/dry-guard.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/dry-guard.sh
# Register the hook in your Claude / Cursor hooks configuration if required.Requires jq and perl (for portable PascalCase in the collision check).
cp plugins/cline/hooks/* ~/.clinerules/hooks/
chmod +x ~/.clinerules/hooks/*Requires jq.
mkdir -p .cursor/rules
cp plugins/cursor/rules/*.mdc .cursor/rules/mkdir -p .kilo/rules
cp plugins/kilo/rules/*.md .kilo/rules/Restart your AI coding assistant after installing.
| Plugin | Dependency |
|---|---|
| auto-lint-fix | Biome |
| auto-summarize-input | Anthropic API key |
| dedup-guard | tsx for TypeScript execution |
| typecheck-guard | TypeScript (tsc) installed in the project |
| Cline hooks | jq |
| All others | None |
See CONTRIBUTING.md.