Skip to main content
Glama

🛡️ RepoGuard

v1.7.1: init is 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:

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

init 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

npx repoguard-rules init

Temporarily unavailable, including all options.

npx repoguard-rules audit

Evaluates entire codebase and returns an Architectural Health Score (A+ to F).

npx repoguard-rules audit --format=sarif

Generates standard OASIS SARIF v2.1.0 for GitHub Code Scanning integration.

npx repoguard-rules audit --format=json

Outputs machine-readable JSON for custom CI/CD pipelines.

npx repoguard-rules diff

Audits uncommitted git diffs against architectural rules in real-time.

npx repoguard-rules fix

Analyzes codebase and generates actionable before/after architectural refactoring suggestions.

npx repoguard-rules mcp

Launches the Model Context Protocol stdio server for AI agents.

npx repoguard-rules hook install

Configures local .git/hooks/pre-commit to prevent rule breaches.

npx repoguard-rules rules

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 (db.commit()) inside route handlers.

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 (_ = err) in Go.

RULE-RS-01

Error Handling

Warning

Flags unsafe .unwrap() or .expect() in production Rust logic that cause thread crashes and panics.

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 (BEGIN PRIVATE KEY).

RULE-09

Security

Critical

Flags private secrets exposed via public prefixes (NEXT_PUBLIC_*SECRET*, VITE_*SECRET*).

RULE-03

Type Safety

Warning

Forbids lazy : any and as any escape hatches in TypeScript.

RULE-04

Code Quality

Info

Enforces structured logging instead of raw console.log.

RULE-05

Next.js / SSR

Error

Prevents hydration mismatch from browser globals (window/localStorage).

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

Tier

Price

Ideal For

What's Included

Open Source

$0 (Free Forever)

Solo builders & public repos

Unlimited local CLI scans, .cursorrules, CLAUDE.md, MCP Server, pre-commit hooks, all 16 built-in rules

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

Star History Chart


👥 Contributors & Community

Special thanks to the open source engineers contributing to RepoGuard:

🌟 Support & Community

If RepoGuard helps keep your AI coding clean, consider giving this repository a ⭐ Star!

Available Tools

4 tools
repoguard_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

    A3.5/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      AI 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 npm
      26
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Framework-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
    • A
      license
      A
      quality
      B
      maintenance
      MartinLoop 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.
      24
      229 npm
      286
      Apache 2.0