Repo Guard CLI

Your repository's memory. Your team's consistency. Your AI's context.

Repo Guard CLI is a local-first CLI tool that learns your repository's architecture, conventions, and patterns, then analyzes every change against that knowledge before it lands in your codebase.

It doesn't enforce static rules you write by hand. It discovers what your team actually does, and flags when a change, whether written by a human or an AI, doesn't fit.

npx repo-guard-cli init
npx repo-guard-cli check
npx repo-guard-cli learn ./docs/architecture.md
npx repo-guard-cli dashboard

🎯 Why

The problem

Your repository has unwritten rules. Every team has them.

• "We use generated API clients, not raw fetch."
• "New state goes through Zustand, not Redux."
• "The payments directory shouldn't import from the UI kit."
• "Date formatting is always done with date-fns."

These rules aren't in any config file. They live in PR comments, Slack threads, and tribal knowledge. New team members violate them. AI generated code violates them. Even seasoned engineers drift from them during a late night commit.

The solution

Repo Guard connects three things:

1. Your repository's actual code and Git history — what people actually do
2. Your AI context files (CLAUDE.md, AGENTS.md, SKILL.md) — what your team says it does
3. An LLM — to reconcile the evidence and spot meaningful inconsistency

The result is a living knowledge model, version-controlled, reviewable, and shared across your team, that grows with your codebase.

✨ Awesome Features

🔍 Deep Code Sampling

Reads files across all modules, proportionally distributed. The LLM can identify real patterns, conventions, and architecture.

🧠 Multi-Module Awareness

If your monorepo has 6 modules with 6 teams, Repo Guard discovers each one individually. Run init from a subdirectory and it scopes knowledge to that module only. The check command walks up the tree to find the closest knowledge directory for each changed file.

📚 Manual Knowledge Augmentation (learn)

Found a pattern the initial scan missed? Run repo-guard-cli learn ./path/to/file.md or repo-guard-cli learn ./src/shared/ to augment knowledge without rescanning the entire repo. The LLM compares the new content against existing knowledge and proposes additions, modifications, and deletions.

🔄 Auto-Evolving Knowledge

When check detects that a change isn't a violation but a legitimate evolution of the codebase, it prompts you: "This change seems to introduce a new pattern. Accept it as knowledge?" If you accept, it automatically writes the new knowledge item — no manual file editing.

🔧 Multiple LLM Providers

Anthropic, OpenAI, DeepSeek — or use external agent mode (file-based or Claude headless) with no API key at all. Every engineer on the team can use a different provider, sharing the same committed knowledge.

📦 Version-Controlled Knowledge

Knowledge is written as .repo-guard/knowledge/*.json files that you commit to Git. Every change goes through a normal PR review. Full history, full accountability.

🏗️ How It Works

Repository ──► Deterministic Analysis ──► Evidence Package ──► LLM ──► Knowledge
    │               │                            │                       │
    │               │                            │                       ▼
    │          • File structure              • Source code         Version-controlled
    │          • Import graphs               • Import blocks       knowledge files
    │          • Git history (optional)      • Diffs               in .repo-guard/
    │          • AI context files            • Knowledge items
    │          • Declared conventions        • No secrets

Phase 1: Discovery (init)

Repo Guard scans your repository and builds a knowledge model from:

• Repository structure — languages, frameworks, package manager, monorepo layout
• Source code — lines of actual code, proportionally sampled from each module
• Import graphs — module boundaries, external dependencies, dependency direction
• Git history — meaningful commits, migrations, refactors, dependency changes
• AI context files — CLAUDE.md, AGENTS.md, SKILL.md (parsed deterministically)
• Declared conventions — cross-referenced against observed code to detect instruction drift

The LLM receives all this and returns structured knowledge written to .repo-guard/knowledge/:

| File | Content | |---|---| | architecture.json | Module boundaries, dependency direction, layer separation | | conventions.json | Naming, file organization, import patterns, error handling | | patterns.json | Repeated implementation approaches | | decisions.json | Architectural choices evident in the code | | exceptions.json | Known deviations from conventions | | repository.json | Languages, frameworks, workspace type | | declared/*.json | Parsed AI context file rules |

Phase 2: Change Analysis (check)

Every time you make changes, check analyzes them against established knowledge:

Change ──► Structural Diff ──► Relevant Knowledge ──► Evidence Package ──► LLM ──► Findings

It answers questions like:

• "Does this new import violate a module boundary?"
• "Is this introducing a library we systematically removed 6 months ago?"
• "Does this contradict what our CLAUDE.md says about API patterns?"
• "Is the codebase changing direction?"

Phase 3: Continuous Learning (learn + check evolution)

Two paths to grow your knowledge:

1. Explicit: repo-guard-cli learn <path> — manually augment from any file or folder
2. Implicit: During check, accepts knowledge evolution proposals that auto-write

📋 Commands

repo-guard-cli init 🚀

Initialize Repo Guard in your repository. Runs the interactive setup wizard and performs full repository discovery to generate knowledge files.

cd your-project
npx repo-guard-cli init

# Skip Git history by default (use --with-git to enable)
npx repo-guard-cli init

# Include Git history analysis (captures migrations, refactors)
npx repo-guard-cli init --with-git

# Preview what would be sent to the LLM (no API call)
npx repo-guard-cli init --dry-run

# Show detailed logs during discovery
npx repo-guard-cli init --verbose

# Just change LLM provider/model/key — skip all discovery
npx repo-guard-cli init --config-only

What it does:

1. Interactive LLM provider setup (Anthropic / OpenAI / DeepSeek / External Agent)
2. File scanning (respects .gitignore, configurable ignore patterns)
3. Source code analysis (imports, exports, symbols, React components)
4. Git history analysis (migrations, structural commits)
5. AI context file parsing (CLAUDE.md, AGENTS.md, SKILL.md)
6. LLM analysis → knowledge generation
7. Writes .repo-guard/knowledge/*.json
8. Optional pre-commit hook installation

🔑 Key detail — scoped init: Run from a subdirectory to limit discovery to that module:

cd some-folder/src/ui
npx repo-guard-cli init

This creates .repo-guard/ in that directory — perfect for monorepos with multiple teams.

repo-guard-cli check 🔬

Analyze changes against repository knowledge. The core analysis pipeline.

# Analyze working tree changes
npx repo-guard-cli check

# Review an entire module against repository knowledge (no git changes needed)
npx repo-guard-cli check --path src/some-folder/ui/somethin/something

# Compare against a branch (ideal for CI)
npx repo-guard-cli check --base origin/main

# Analyze staged changes (pre-commit hook)
npx repo-guard-cli check --pre-commit

# CI mode — JSON output, no prompts, exit codes
npx repo-guard-cli check --ci --output json

# Override provider or model for this run
npx repo-guard-cli check --provider deepseek --model deepseek-v4-flash

# Continue an external agent analysis
npx repo-guard-cli check --continue

# Control output strictness
npx repo-guard-cli check --min-confidence 0.7 --fail-on warning

🔑 Key detail — automatic knowledge root resolution: The check command doesn't just look at the repo root. It walks up from each changed file to find the closest .repo-guard/knowledge/ directory. This means if you have:

project/
├── .repo-guard/
├── module-a/.repo-guard/
└── module-b/.repo-guard/

Changing a file in module-a uses module-a's knowledge. A file in the root uses root knowledge. Each module's conventions are independently enforced.

Output severity levels:

| Severity | Meaning | Exit Code | |---|---|---| | info | Low-confidence observation | 0 | | warning | Likely convention violation | 0 (or 5 with --fail-on warning) | | error | Explicit hard rule violation | 1 |

🔑 Key detail — auto-evolving knowledge: When check detects a pattern change that represents a legitimate codebase evolution (not a violation), it prompts you. If you accept, the new convention is automatically written to your knowledge files.

🔑 Key detail — context-aware evidence (Claude Code headless): The evidence sent to the LLM is sized to the provider's context window. For smaller windows (e.g. Claude's 200K), the per-file full content is dropped and long diffs are trimmed (import blocks and structural metadata are always kept) so the model gets a focused, non-overflowing package — DeepSeek (1M context) keeps the full evidence. You can tune Claude Code headless runs with environment variables:

| Env var | Values | Default | Purpose | |---|---|---|---| | REPO_GUARD_CLAUDE_MAX_TURNS | integer > 1 | 20 | Max agent turns for claude -p. Bump for deeper analysis; keep ≥ 2 (1 fails immediately). | | REPO_GUARD_CLAUDE_EFFORT | low | medium | high | xhigh | max | (Claude default) | Reasoning effort for check. high/xhigh produce more thorough output at higher cost/latency, with no change to turns or context. | | REPO_GUARD_CLAUDE_TIMEOUT_MS | ms | 1200000 (20 min) | Hard timeout for claude -p (auto-extends while the session transcript is still being written). | | REPO_GUARD_MAX_OUTPUT_TOKENS | integer | 16384 | Output-token budget for the check LLM call (all providers). If a reasoning model exhausts it and returns an empty result (finish_reason length), raise it (e.g. 32768). |

Example:

REPO_GUARD_CLAUDE_EFFORT=high npx repo-guard-cli check

Troubleshooting — "LLM returned invalid JSON (empty response)": The provider returned an HTTP 200 with an empty message.content. This is usually a reasoning model exhausting the output budget (finish_reason: length) on a large review — the error now reports the exact finish_reason and a raw-response snippet. Fix: REPO_GUARD_MAX_OUTPUT_TOKENS=32768 npx repo-guard-cli check. If it persists, check the configured model name in repo-guard config show.

🔑 Key detail — generic code review (--review): Run a review of just the changed code — syntax, bugs, code quality, and suggested fixes — without repository knowledge:

# Generic code review of the working-tree changes
npx repo-guard-cli check --review

# Generic review in CI (JSON output, no prompts)
npx repo-guard-cli check --review --ci --output json

In --review mode the tool ignores .repo-guard knowledge entirely: no knowledge loading, no deterministic concerns, no knowledge evolution. It still detects the changes and sends them to your configured LLM with a generic review prompt, returning findings with the code_quality category. It works even in a repo that was never initialized.

Using both for a full review process: the two checks are complementary and are designed to be run together — check for architecture/convention/knowledge violations, check --review for a generic engineering review:

# Architecture & convention compliance against repo knowledge
npx repo-guard-cli check

# Generic code quality review of the same changes
npx repo-guard-cli check --review

🔑 Key detail — full-file review (--review-full): Like --review, this is a generic code review with no repository knowledge — but instead of sending the diff, it sends the entire contents of every changed file so the reviewer sees full surrounding context (not just changed lines):

# Generic review using full file contents instead of diffs
npx repo-guard-cli check --review-full

# In CI (JSON output, no prompts)
npx repo-guard-cli check --review-full --ci --output json

What it does:

• Same generic review prompt and code_quality category as --review.
• Full file contents are sent for every changed file (diff trimming is disabled). This is especially useful for large files where a diff alone misses the surrounding logic, or for reviewing newly added files in full.
• Use --review-full when you want depth and context; use --review when you want a faster, cheaper pass focused on the changed lines.

⚠️ Token usage: --review-full sends the complete source of every changed file, so it consumes significantly more tokens (and costs more) than --review or a normal check. It also makes it easier to hit a provider's context-window limit on large changes — keep that in mind for big diffs or small-window providers (e.g. Claude's 200K).

🔑 Key detail — module check (--path): Check an entire directory/module against repository knowledge, regardless of Git changes. It walks the directory on disk (skipping ignored dirs like node_modules, dist, target) and reviews every source file with its full contents — perfect for auditing a big module as a whole:

# Review a whole module — git-root-relative path works from anywhere in the repo
npx repo-guard-cli check --path src/some-folder/ui/somethin/something

# From inside the module — path relative to your current directory
npx repo-guard-cli check --path .

# In CI with JSON output
npx repo-guard-cli check --path src/some-folder/ui/somethin/something --ci --output json

Relative --path values are resolved against your current directory first, then the git root — so --path . (from inside the module) and --path src/some-folder/... (a git-root-relative path from any subdirectory) both work.

What it does:

• Treats each source file as newly added and sends full file contents to the LLM, so the whole module is reviewed — not just a diff.
• Uses the standard knowledge-based pipeline (architecture, conventions, patterns, decisions, exceptions + deterministic concerns + auto-evolving knowledge), with the closest .repo-guard resolved per file — so a module with its own scoped knowledge is enforced correctly.
• Respects the provider context budget: on big modules the evidence builder drops/trims full content so the prompt still fits the window.

⚠️ Does not mix with Git change detection: --path reviews what's on disk and ignores --base and --pre-commit (a warning is printed if you pass them). Use --base for branch comparisons and --path for whole-module reviews — they are separate modes. Ignored directories (node_modules, dist, target, …) are skipped.

repo-guard-cli learn <path> 📖

Manually augment knowledge from any file or folder. No re-scanning the entire repo.

# Learn from a markdown file
repo-guard-cli learn ./docs/team-conventions.md

# Learn from a folder (scans .md, .ts, .tsx, .js files)
repo-guard-cli learn ./src/shared/components/

# Learn from an AI context file
repo-guard-cli learn ./CLAUDE.md

What it does:

1. Reads the file (or all code/markdown files in the folder)
2. Compares content against existing knowledge
3. LLM proposes additions, modifications, and deletions
4. Shows a color-coded summary
5. Asks for confirmation before applying

🔑 Key detail — automatic knowledge root: The learn command walks up from the target path to find the closest .repo-guard/ directory. Running learn ./module-a/src/Button.tsx automatically augments module-a/.repo-guard/ — not the root.

repo-guard-cli config ⚙️

Manage LLM configuration. Reads from ~/.config/repo-guard/config.json.

# Show current configuration
repo-guard-cli config show

# Set provider
repo-guard-cli config set-provider deepseek
repo-guard-cli config set-provider external-agent

# Set model
repo-guard-cli config set-model deepseek-v4-flash

# Set external agent type
repo-guard-cli config set-agent-type claude-headless

# Get API key setup instructions
repo-guard-cli config set-api-key

repo-guard-cli status 📊

Check initialization state and knowledge summary.

repo-guard-cli status

Reports: initialization status, knowledge file count, total items per category, config presence, next-step action.

repo-guard-cli inspect-request 🔍

Preview exactly what would be sent to the LLM before making a call. Nothing is sent until you run the actual command.

repo-guard-cli inspect-request

Shows: source file count, external dependencies, Git history stats, AI context files, directory structure, top dependencies, estimated token count — exactly what the LLM would receive, without sending anything.

🏗️ Configuration Model

Repo Guard uses a split configuration approach:

Shared (committed to Git)

.repo-guard/config.json — analysis policies shared across the team:

{
  "version": 1,
  "analysis": { "historyDepth": 5000 },
  "policies": { "minimumConfidenceForWarning": 0.85 },
  "ignorePatterns": ["**/generated/**"]
}

Local (never committed)

~/.config/repo-guard/config.json — your personal LLM setup:

{
  "mode": "direct-api",
  "provider": "deepseek",
  "model": "deepseek-v4-flash"
}

API Key Resolution

Keys are resolved in order:

1. Environment variable (DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, etc.)
2. Local config file (with restrictive permissions)
3. OS credential store (keychain)

Your API key is never written to: .git/, node_modules/, .repo-guard/, source files, knowledge files, logs, stdout, or error messages.

📁 Knowledge File Structure

.repo-guard/
├── config.json
├── knowledge/
│   ├── repository.json
│   ├── architecture.json
│   ├── conventions.json
│   ├── patterns.json
│   ├── decisions.json
│   ├── exceptions.json
│   └── declared/
│       ├── claude.json
│       ├── agents.json
│       └── ...
└── state/
    └── analysis.json

Each knowledge file follows the format:

{
  "items": [
    {
      "id": "conv-component-naming",
      "type": "convention",
      "statement": "React components use PascalCase filenames with default exports",
      "scope": "packages/ui/src/components",
      "confidence": 0.98,
      "source": "observed",
      "status": "active",
      "evidence": [
        { "type": "file", "value": "packages/ui/src/components/Button.tsx" }
      ]
    }
  ]
}

🚀 Quick Start

# 1. Initialize
cd your-repo
npx repo-guard-cli init

# 2. Review what was created
git diff
git add .repo-guard
git commit -m "Initialize Repo Guard CLI knowledge"

# 3. Make changes, then check them
npx repo-guard-cli check

# 4. Augment knowledge as your codebase evolves
npx repo-guard-cli learn ./docs/new-conventions.md

# 5. Visualise & edit your knowledge in the browser
npx repo-guard-cli dashboard

� Knowledge Dashboard

See your knowledge — and fix it — in a human-friendly web UI.

After init, run:

npx repo-guard-cli dashboard

This starts a local server (default http://127.0.0.1:4173) and opens your browser. The dashboard reads your .repo-guard/knowledge/*.json files and presents every item as a readable card, so you can visualise your repository's conventions, architecture, decisions, patterns, and exceptions without opening a single JSON file.

What you can do

• Browse — every knowledge item is a card with its type, status, confidence bar, scope, and source, plus the statement, the reasoning behind the confidence, and its evidence (expandable).
• Edit — change the statement, scope, source, status, reasoning, and evidence, and tune the confidence with a slider. id and type are read-only to keep references stable.
• Add — use "+ Add item" in any category to record a convention, decision, pattern, or exception you want check to respect.
• Delete — remove an item that is no longer accurate (with a confirmation).
• Search & filter — filter by text or status to find what you need fast.
• Overview — repo identity, per-category counts, and a confidence distribution at a glance.

Every change is written straight back to the same .repo-guard/knowledge/*.json files — the version-controlled source of truth. git diff shows exactly what you changed, and the next repo-guard-cli check uses the updated knowledge.

Which knowledge set does it load?

• Default: the .repo-guard/knowledge closest to the directory you run the command from (walks up). In a monorepo, running inside a module loads that module's knowledge.
• Pick another: pass --path to load any directory's knowledge set.

# Default — closest knowledge to your current directory
npx repo-guard-cli dashboard

# A specific module or repo
npx repo-guard-cli dashboard --path ./packages/checkout

# Options
npx repo-guard-cli dashboard --port 8080     # custom port
npx repo-guard-cli dashboard --no-open       # don't auto-open the browser

The loaded knowledge root is shown at the top of the dashboard, and all edits save to that same set — so you're always editing the files you're looking at.

Notes

• repository.json and declared/* (AI instruction files) are shown read-only in this version.
• The server binds to 127.0.0.1 only and stays up until you press Ctrl+C.

�📦 Requirements

• Node.js 18+
• Git repository
• TypeScript, JavaScript, Python, or JVM (Java, Scala, Kotlin, Groovy) project
• Optional: Anthropic, OpenAI, or DeepSeek API key (or use external agent mode)

🛠 Installation

# No installation needed — run directly with npx
npx repo-guard-cli init

# Or install globally
npm install -g repo-guard-cli
repo-guard-cli init

For Teams

Every engineer chooses their own LLM

Engineer A uses Claude. Engineer B uses GPT-4o. Engineer C uses DeepSeek. Engineer D has no API key and uses external agent mode.

All four share the same committed knowledge model. The LLM is a personal choice, like your editor.

Knowledge is version-controlled

.repo-guard/ is committed to Git. Every knowledge update goes through a normal PR review. Full history, full accountability.

Multi-module, multi-team

Each module can have its own .repo-guard/ with independently discovered knowledge. The check and learn commands automatically resolve to the closest knowledge directory.

Detects declared-vs-actual drift

Your team's CLAUDE.md says "all API calls go through generated clients" — but someone added 34 raw fetch() calls. Repo Guard detects this discrepancy and flags it during discovery.

🧠 Philosophy

Repo Guard is not "AI that reviews your PR." Many tools do that.

Repo Guard is:

A deterministic engine that converts your repository, its history, and its AI-context documentation into structured evidence. An LLM reasons over that evidence to determine whether a change is consistent with your repository's established direction.

The LLM is replaceable. The evidence pipeline is the product.

🗺️ Roadmap

• [x] Repository discovery and knowledge generation (init)
• [x] Change analysis against knowledge (check)
• [x] Manual knowledge augmentation (learn)
• [x] Auto-evolving knowledge during check
• [x] Multi-module knowledge (per-directory .repo-guard/)
• [x] Deep code sampling
• [x] DeepSeek V4 Flash support
• [x] CI mode with exit-code-based gating
• [x] External agent mode (Claude headless + file-based)
• [x] Pre-commit hook integration
• [ ] GitHub/GitLab PR integration
• [x] Python support (imports, symbols, Django/Flask/FastAPI detection)
• [x] Java/JVM support (Java, Scala, Kotlin, Groovy — imports, symbols, Maven/Gradle/SBT detection, Spring/JPA/JUnit frameworks)
• [x] Knowledge dashboard (local web UI to browse, add, edit, and delete knowledge items)
• [ ] Ollama support for fully local LLM
• [ ] VS Code extension

License

MIT