RepoGuard
RepoGuard MCP server provides tools to audit repositories, diffs, and code snippets against 16 architecture/security rules and expose those rules.
repoguard_audit: Audit a repository or directory against 16 Clean Architecture & Security guardrails across TypeScript, Python, Golang, Rust, and secrets detection; accepts an optional directory path.repoguard_diff: Audit uncommitted git changes in real time to detect architectural drift before commit.repoguard_get_rules: Return all 16 active architectural rules to help prevent AI hallucination of invalid layering patterns.repoguard_fix: Analyze a provided code snippet and filename, then return actionable clean architecture refactoring suggestions.
Generates a tailored .github/copilot-instructions.md file that injects repository-specific architectural rules and guardrails into GitHub Copilot's context to prevent AI code rot.
🛡️ RepoGuard
v1.7.1:
initis temporarily unavailable while its filesystem safety is being redesigned. Other commands remain available.New in v1.7.0: Rust panic safety, expanded secret detection, and MCP Tools + Resources + Prompts.
🎮 Try it in your browser: RepoGuard Interactive Playground — Audit code snippets in real-time with zero install.
⚡ The Problem
AI coding assistants (Cursor, GitHub Copilot, Claude Code, Windsurf) write 300 lines of code in seconds. However, without strict repository guardrails, they frequently introduce AI Code Rot:
Bypass Architectural Layers: Run raw database queries (Prisma, Drizzle, SQLAlchemy, GORM, SQLx, Diesel) directly inside UI components or HTTP handlers.
Reinvent Existing Helpers: Write duplicate date/string utilities instead of importing from
/utilsor shared packages.Escape Type Safety & Error Handling: Scatter
: anyin TypeScript, discard errors with_ = errin Go, or use panic-prone.unwrap()in Rust production code.Leak Sensitive Secrets: Hardcode AI/cloud provider tokens, embed database credentials in connection URLs, or expose secrets with the
NEXT_PUBLIC_prefix.
RepoGuard acts as an automated architecture supervisor: it analyzes code and diffs, runs an MCP server with Tools, Resources, and Prompts, and can audit Pull Requests with a manually configured workflow. Context-file generation is temporarily unavailable in v1.7.1.
Related MCP server: vibelogic
🚀 Quickstart
Audit a repository (zero installation required):
npx repoguard-rules auditinit is temporarily unavailable in v1.7.1, including --dry-run, --force, and --with-ci. It exits with an error before scanning or changing project files. It does not generate context files or a CI workflow. Safe initialization will be addressed separately.
You can also install globally with npm install -g repoguard-rules, then run repoguard audit. Review results locally. Hook installation is a separate command and modifies the repository.
🤖 Native Model Context Protocol (MCP) Server
RepoGuard ships with a built-in, zero-dependency MCP Server implementing the full 3-pillar standard (Tools, Resources, and Prompts) for Claude Desktop, Claude Code, Cursor, and Windsurf.
Connect to Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"repoguard": {
"command": "npx",
"args": ["-y", "repoguard-rules@1.7.1", "mcp"]
}
}
}Connect to Cursor (~/.cursor/mcp.json or .cursor/mcp.json):
{
"mcpServers": {
"repoguard": {
"command": "npx",
"args": ["-y", "repoguard-rules@1.7.1", "mcp"]
}
}
}MCP Capabilities:
🛠️ Tools:
repoguard_audit: Full repository audit against 16 architectural guardrails.repoguard_diff: Real-time audit of uncommitted git changes to catch AI drift before commit.repoguard_get_rules: Returns all 16 active architectural rules to prevent AI hallucination.repoguard_fix: Analyzes code snippets and returns actionable refactoring plans.
📦 Resources:
repoguard://rules: Direct JSON access to all architectural rules and remediation advice.repoguard://health: Real-time codebase health score and violation breakdown.
💡 Prompts:
architectural_review: Pre-configured prompt instructing AI agents to review diffs against Clean Architecture.clean_architecture_refactor: Pre-configured prompt to decouple controllers into Service and Repository layers.
🛠️ CLI Commands & Formats
Command | Description |
| Temporarily unavailable, including all options. |
| Evaluates entire codebase and returns an Architectural Health Score (A+ to F). |
| Generates standard OASIS SARIF v2.1.0 for GitHub Code Scanning integration. |
| Outputs machine-readable JSON for custom CI/CD pipelines. |
| Audits uncommitted git diffs against architectural rules in real-time. |
| Analyzes codebase and generates actionable before/after architectural refactoring suggestions. |
| Launches the Model Context Protocol stdio server for AI agents. |
| Configures local |
| Displays all 16 built-in architectural rules and descriptions. |
Sensitive diagnostic output
RepoGuard scans source locally but does not echo raw source excerpts in CLI audit/fix reports, PR review comments, JSON, or MCP health results. JSON retains the codeSnippet field for compatibility, with a fixed [source excerpt withheld to avoid exposing credentials] value. Rule IDs, file paths, line numbers, severity, and safe explanations and suggestions remain available (paths that match a credential pattern are withheld); open the referenced line in your own editor to inspect it. This reduces the risk of copying a detected credential into logs or a persistent PR comment; it does not guarantee that every possible secret will be detected in source code.
MCP prompt templates omit user-provided code when they recognize a credential pattern. Do not paste credentials into prompts, filenames, or third-party services; revoke any real credential already committed to a repository. No scan removes secrets from git history.
Ignoring Files & Folders (.repoguardignore)
Add a .repoguardignore file to your root directory to skip specific files or directories:
# .repoguardignore
legacy/
migrations/
test/fixtures/🛡️ Built-in Architectural Rules (16 Active Guardrails)
Rule ID | Category | Severity | Guardrail Enforced |
RULE-01 | Architecture | Error | Prohibits raw ORM/DB queries in UI components and Controllers (TS/JS). |
RULE-PY-01 | Architecture | Warning / Critical | Enforces FastAPI layer separation; forbids direct DB queries and raw commits ( |
RULE-GO-01 | Architecture | Warning / Critical | Enforces Clean Architecture in Go; prohibits raw database/GORM operations inside Gin, Fiber, or Echo HTTP handlers. |
RULE-GO-02 | Error Handling | Warning | Flags unchecked errors silenced via blank identifier ( |
RULE-RS-01 | Error Handling | Warning | Flags unsafe |
RULE-RS-02 | Architecture | Warning | Enforces Clean Architecture in Rust (Axum, Actix-web, Rocket); forbids direct SQLx / Diesel queries inside route handlers. |
RULE-02 | Security | Critical | Flags hardcoded secrets, private keys, and API tokens. |
RULE-SEC-01 | Security | Critical | Detects provider-format AI/cloud tokens and credential-bearing database URLs in source and supported config files. |
RULE-SEC-02 | Security | Critical | Flags unencrypted private cryptographic key headers ( |
RULE-09 | Security | Critical | Flags private secrets exposed via public prefixes ( |
RULE-03 | Type Safety | Warning | Forbids lazy |
RULE-04 | Code Quality | Info | Enforces structured logging instead of raw |
RULE-05 | Next.js / SSR | Error | Prevents hydration mismatch from browser globals ( |
RULE-06 | Security | Critical | Detects SQL injection hazards in raw query string interpolations. |
RULE-07 | API Design | Warning | Enforces schema validation (Zod/Pydantic) on incoming request payloads. |
RULE-08 | DRY Principle | Info | Prevents AI assistants from duplicating existing common utility helpers. |
🤖 GitHub Action & Security Integration
RepoGuard dogfoods its own architecture on every push. Workflow generation via init is unavailable in v1.7.1. Do not use the v1.7.0 Action for PR comments containing sensitive code. The example below is this repository's own CI job:
# .github/workflows/ci.yml
name: CI & Architecture Guard
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
audit:
name: Unit Tests & Dogfood Audit
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: Run Architecture & Stack Tests
run: npm test
- name: Dogfood Audit (RepoGuard on RepoGuard)
run: node bin/repoguard.js audit --strictGitHub Code Scanning (SARIF v2.1.0):
- run: npx repoguard-rules audit --format=sarif > repoguard.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: repoguard.sarif💎 Plans & Enterprise Upgrades
RepoGuard is 100% free and open-source for public repositories and local development. For automated CI/CD PR enforcement, private teams, and custom architectural rule engines:
Tier | Price | Ideal For | What's Included |
Open Source | $0 (Free Forever) | Solo builders & public repos | Unlimited local CLI scans, |
Developer Pro | $12 / month | Independent engineers & contractors | Unlimited private repositories, automated PR Review Bot, custom rules engine, secret leak detector |
Engineering Team | $39 / month | Startups & engineering orgs | Up to 5 devs, GitHub Org-wide CI/CD merge blocker, SOC2 architecture audit logs, Slack/Discord alerts |
👉 Subscribe to Developer Pro ($12/mo) • Upgrade Team ($39/mo) • 🇧🇷 Pagar no PIX (R$ 67 à vista)
📈 Star History
👥 Contributors & Community
Special thanks to the open source engineers contributing to RepoGuard:
@taylormatematica-beep (Lead Maintainer & Author)
@NihalPN — Authored
RULE-PY-01& FastAPI architectural guardrails (PR #3)
🌟 Support & Community
🌐 Documentation & Live Hub: https://taylormatematica-beep.github.io/repoguard/
📦 NPM Registry: https://www.npmjs.com/package/repoguard-rules
🐱 Product Hunt: https://www.producthunt.com/products/repoguard
If RepoGuard helps keep your AI coding clean, consider giving this repository a ⭐ Star!
Available Tools
4 toolsrepoguard_auditB
Audits a repository or directory against 16 Clean Architecture & Security guardrails (TypeScript, Python, Golang, Rust, Secrets 2.0) in ~12ms
Inputs: directory.
repoguard_diffB
Audits uncommitted git changes in real-time to detect architectural drift before commit
Inputs: no named parameters.
repoguard_fixC
Analyzes a code snippet and returns actionable clean architecture refactoring suggestions
Inputs: code (required), filename (required).
repoguard_get_rulesA
Returns all 16 active architectural rules to prevent AI hallucination of invalid layering patterns
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct action: full-repo audit, uncommitted-diff audit, rule retrieval, and snippet-level fix suggestions. audit and diff share a domain but differ clearly in scope, and fix targets snippets rather than repos, so boundaries are mostly clear with minor potential overlap between audit and fix.
All four tools use the repoguard_ prefix followed by concise, lowercase verbs/nouns (audit, diff, get_rules, fix). The convention is consistent throughout with no style mixing.
Four tools is on the lean side but each one maps to a distinct need (audit, drift check, rules reference, fix suggestion) for a focused guardrail server. It is well-scoped, though slightly thin compared to a fuller lifecycle surface.
The surface covers auditing, incremental diff checks, rule introspection, and remediation suggestions, which are the core lifecycle for an architecture guardrail. Minor gaps exist (e.g., no rule configuration/customization or CI/report export), but agents can work around them.
Maintenance
Related MCP Connectors
Enforces architectural invariants and code quality rules inside your AI agent's edit loop.
AI code governance and code review for Claude Code, Copilot and Cursor. Checks rules and security.
Checks AI-written code for leaked keys and made-up packages, on your machine. Never uploads code.
Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAI Constraint Engine that enforces CLAUDE.md, .cursorrules, and AGENTS.md rules as laws. 51 MCP tools for semantic conflict detection, patch review, drift scoring, pre-commit hooks, and Guardian Mode. Catches euphemisms, temporal evasion, and hidden violations that keyword matching misses.507 npm26MIT
- AlicenseAqualityDmaintenanceA deterministic architecture audit engine for Cursor. It enforces visual Mermaid protocols to prevent LLM hallucinations, ensuring AI modifies code based on strict blueprints.1MIT
- AlicenseNot gradedqualityDmaintenanceFramework-agnostic architecture-rule enforcement for AI agents: analyzes Python codebases import graphs against declarative rulesets to report layer, forbidden-import, and cycle violations with file and line numbers. Supports MCP, OpenAI, Anthropic, LangChain, LlamaIndex, and CLI integrations.MIT
- AlicenseAqualityBmaintenanceMartinLoop is the independent governance and financial control layer for AI coding agents. Set hard spend limits, prevent runaway loops, enforce verification, trigger rollback on failure, and generate auditable receipts showing what changed, what it cost, and whether the work passed.24229 npm286Apache 2.0