Repoguard

🛡️ RepoGuard

The Architecture Guardian for AI-Assisted Codebases.

Stop AI from turning your repository into architectural spaghetti across TypeScript, Python, Golang, and Rust.

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:

1. Bypass Architectural Layers: Run raw database queries (Prisma, Drizzle, SQLAlchemy, GORM, SQLx, Diesel) directly inside UI components or HTTP handlers.
2. Reinvent Existing Helpers: Write duplicate date/string utilities instead of importing from /utils or shared packages.
3. Escape Type Safety & Error Handling: Scatter : any in TypeScript, discard errors with _ = err in Go, or use panic-prone .unwrap() in Rust production code.
4. 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 generates strict, customized .cursorrules, CLAUDE.md, and .windsurfrules context files, verifies pre-commit diffs in ~12ms, runs an MCP server with Tools, Resources, and Prompts, and performs inline audits on every Pull Request.

🚀 Quickstart

Run directly in any repository (zero installation required):

npx repoguard-rules init

Or install globally:

npm install -g repoguard-rules
repoguard init

What happens in 2 seconds:

• 🔍 Auto-detects your tech stack (Next.js, NestJS, Express, FastAPI, Django, Gin, Fiber, Axum, Actix-web, Prisma, GORM, SQLx, Diesel, etc.).
• 🔐 Audits code and supported config files (.env, .env.*, .json, .yaml, .toml, .pem, .key) for provider tokens and embedded database credentials.
• 📝 Generates tailored .cursorrules (for Cursor AI).
• 🤖 Generates a comprehensive CLAUDE.md (for Claude Code).
• 🌊 Generates .windsurfrules (for Windsurf IDE).
• 🛡️ Generates .github/copilot-instructions.md (for GitHub Copilot).
• ⚙️ Configures pre-commit guard hooks & CI workflow.

🤖 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.0", "mcp"]
    }
  }
}

Connect to Cursor (~/.cursor/mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "repoguard": {
      "command": "npx",
      "args": ["-y", "repoguard-rules@1.7.0", "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

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)

🤖 GitHub Action & Security Integration

RepoGuard dogfoods its own architecture on every push. You can add continuous architectural enforcement to your CI/CD pipeline using the official Action:

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

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

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