Agentic Gatekeeper

Autonomous AI agent that enforces your Markdown rules on every commit.

Write rules in plain English → Stage your code → The Gatekeeper auto-patches violations before you push.

🧩 The Problem

Teams invest heavily in documenting their engineering standards — architecture decisions, security guardrails, coding conventions — in files like CONTRIBUTING.md, ARCHITECTURE.md, or AGENTS.md. But nobody enforces them. Whether code is written by a human or generated by an AI assistant like Copilot, rules silently drift, technical debt compounds, and PR reviews turn into a battlefield of repeated feedback.

Agentic Gatekeeper fixes this. It reads your Markdown rules, cross-references them against your staged code, and auto-patches violations before you commit — turning your docs from passive suggestions into actively enforced policy.

⚡ See It In Action

Agentic Gatekeeper Demo

Stage your changes in the VS Code Source Control panel.
Click the Shield icon (or run Agentic Gatekeeper: Validate Rules from the Command Palette).
The Gatekeeper auto-patches your code — violations are fixed and re-staged automatically.

Your rules can be literally anything: strict typing, component architecture, security guardrails, naming conventions, or formatting preferences. If you can write it in Markdown, the Gatekeeper can enforce it.

📐 Where to Put Your Rules

Markdown Local Rules vs Global Rules

Scope	Location	Example
Global	`.gatekeeper/*.md`, `AGENTS.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`	`.gatekeeper/security-rules.md`
Directory-scoped	`-instructions.md` or `-gatekeeper.md` anywhere in the tree	`src/components/ui-gatekeeper.md`
Remote	Synced from a GitHub repo into `.gatekeeper/remote/`	See Remote Rules below

Configurable Rules Files Locations

Targeting Specific Files (Rule Globs)

Restrict any rule to specific files using YAML Frontmatter:

---
globs: "src/**/*.ts, src/**/*.tsx"
---
# TypeScript Architecture Rules
1. Every function must have an explicit return type...

🔍 Validate Rules — Audit Your Rules Before Enforcing

Not sure if your rules are specific enough? Run Agentic Gatekeeper: Validate Rules from the Source Control overflow menu to generate a full Rule Report.

Validate Rules Report

The Gatekeeper sends each rule to the AI for a semantic audit and returns:

Enforceability Rating — YES, PARTIALLY, or NO based on how measurable and specific the rule is.
Targets — What file types and directories the rule applies to.
Violation vs. Compliant — Side-by-side code examples showing what breaks the rule and what satisfies it.

This lets you iteratively tighten vague rules until they are fully enforceable — before they ever touch production code.

🔄 Remote Rules — Enforce Standards Across Your Entire Org

Remote Rules Sync Demo

Sync shared engineering standards from a central GitHub repository so every developer on your team validates against the exact same rules — no manual file copying.

Set Agentic Gatekeeper: Remote Rules Repo to owner/repo (e.g., revanthpobala/agentic-gatekeeper-rules).
For private repos, configure your PAT in Agentic Gatekeeper: GitHub Pat.
Run Agentic Gatekeeper: Sync Remote Rules from the Command Palette:

Sync Remote Rules Command

Rules are cached by SHA, stored in a Git-ignored .gatekeeper/remote/ directory, and applied automatically on every analysis.

[!TIP] Live example: Check out agentic-gatekeeper-rules to see how to structure rule files with Glob targeting.

✨ Key Features

Streaming Execution — Patches apply in real-time as batches resolve, drastically reducing wait time.
Intelligent Patch Mode — Auto-switches to fuzzy search-and-replace for large files (>200 lines).
Diff-Only Context — Sends only diffs for massive files (>1000 lines) to preserve token budgets.
Smart Caching — Tracks file content + rule versions for instant re-runs on compliant code.
.gatekeeperignore — Exclude patterns from analysis using standard glob syntax.
Progress Bar — Real-time visual feedback in the notification bar.
Remote Rules Sync — Pull shared rules from any GitHub repository, including GitHub Enterprise.

🚫 Ignoring Files

`.gatekeeperignore` (Recommended)

# Ignore generated code
**/generated/*.ts

# Ignore high-churn legacy files
legacy/utils.js

You can also use agenticGatekeeper.excludePatterns in VS Code Settings.

⚙️ Configuration & API Keys

By default, the Gatekeeper uses your Native IDE Model (Copilot/Gemini). For maximum capability, configure an external provider.

Execution Strategy Settings

Open the Command Palette → Agentic Gatekeeper: Configure API Key
Choose your provider and paste your key.

Supported Providers

Provider	Description	Required Setting
Native IDE (Default)	Built-in Copilot or Gemini. Zero setup.	None
Anthropic	Claude models (e.g., `claude-4.5-sonnet`). Highest reasoning.	`Anthropic API Key`
OpenAI	GPT models (e.g., `gpt-5.2`). Fast and consistent.	`OpenAI API Key`
Google Gemini	Gemini models (e.g., `gemini-3-pro`). Huge context windows.	`Gemini API Key`
OpenRouter	Universal bridge to DeepSeek, Llama, Grok, and hundreds more.	`OpenRouter API Key`
Custom (Local)	Ollama, LM Studio, or any OpenAI-compatible local server.	`Custom Base URL`

Local Models (Ollama / LM Studio)

Custom Base URL: e.g., http://localhost:11434/v1
Custom Model: e.g., llama3 or qwen2.5-coder
Custom API Key: Usually lm-studio or ollama

OpenRouter Headers

OpenRouter Referer: Your project's URL.
OpenRouter Title: Your app's display name.

❓ FAQ

Does this send my code to an external server?

Only if you configure an external AI provider (Anthropic, OpenAI, etc.). The default Native IDE mode routes through your existing Copilot or Gemini session. Selecting Custom (Ollama/Local) keeps everything fully offline on your machine.

Why did the Gatekeeper skip or ignore my file?

Check these in order:

.gatekeeperignore — Works exactly like .gitignore. Drop this file in your workspace root to exclude specific paths from AI analysis.
Rule globs — If your rules have globs: frontmatter, only matching files are analyzed.
Built-in exclusions — node_modules, dist, build, vendor, .next, venv, and other standard dependency/build directories are automatically skipped out of the box so you rarely need a custom ignore file.
Cache — If the file and rules haven't changed since the last run, results are cached. Clear it via the Source Control overflow menu → Agentic Gatekeeper: Clear Analysis Cache.

Clear Cache Menu

Can I use this without GitHub Copilot?

Yes. Configure any supported provider — Anthropic, OpenAI, Google Gemini, OpenRouter, or a fully local model via Ollama or LM Studio. Copilot is just the zero-config default.

Does it work with monorepos?

Yes. Use directory-scoped rules (*-gatekeeper.md) and globs: frontmatter to target specific packages or directories within your monorepo.

What happens when I update my rules?

The cache automatically invalidates. It tracks both file content and rule versions, so any change to your Markdown rules triggers a fresh re-analysis on the next run — no manual cache clearing needed.

Can the AI accidentally destroy my file?

The Patcher has built-in safety checks. If the AI produces a rewrite that suspiciously reduces the file size (a sign of truncation or hallucination), the patch is rejected and your original file is preserved untouched. Additionally, because the extension natively patches your local workspace files, you can always perform a git diff to inspect and verify every single line of code before you commit.

Changelog

See CHANGELOG.md for a complete history of updates and releases.

License

This project is licensed under the MIT License with Dedicated Attribution Clause. See the LICENSE.txt file for details.

Revanth Pobala