ai-guard-plugins

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, and Kilo Code.

Quick Install

npm install -g ai-guard-plugins

Then 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

Alternative: shell script

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

The Problem

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.

What's Included

💳 billing-guard

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.

🔍 dry-guard

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.

🧬 dedup-guard

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>.

🔴 typecheck-guard

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).

📏 code-standards-enforcer

Blocks as any, @ts-ignore, require(), TODO/FIXME placeholders, underscore naming, and logic in index files. Every write/edit is checked.

🧹 auto-lint-fix

Runs biome check --fix --unsafe automatically after every file write. No more commit-time lint failures. Requires Biome.

📦 auto-summarize-input

When input exceeds 10K characters, auto-summarizes while preserving all code, paths, and error messages verbatim. Requires an Anthropic API key.

🧠 capture-insights

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.

📒 transcript-insights (local chats → Markdown)

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=all

Or 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=all

Use --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 Support

| 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/ |

Runtime = programmatic interception that can block operations. Advisory = rules injected into the AI's system prompt as guidelines.

Manual Install

OpenCode / Claude Code

# 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).

Cline

cp plugins/cline/hooks/* ~/.clinerules/hooks/
chmod +x ~/.clinerules/hooks/*

Requires jq.

Cursor

mkdir -p .cursor/rules
cp plugins/cursor/rules/*.mdc .cursor/rules/

Kilo Code

mkdir -p .kilo/rules
cp plugins/kilo/rules/*.md .kilo/rules/

Restart your AI coding assistant after installing.

Requirements

| 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 |

Contributing

See CONTRIBUTING.md.

License

MIT