🎯 What is SemantGuard?

SemantGuard is a VS Code extension that acts as a mandatory enforcement layer between your AI IDE and your codebase. While tools like Semgrep catch patterns, SemantGuard catches intent violations.

Think of it as an architectural airbag that deploys before bad code hits your repository.

View SemantGuard Live !

(semantGuard)[images\trepan_demo.gif]

🚨 The Problem: Context Drift

You ask an AI for "Feature A." It gives you "Feature A," but it also:

• ❌ Reintroduces a security vulnerability you fixed last week
• ❌ Ignores your architectural boundaries (e.g., puts DB logic in the View)
• ❌ Leaks PII into logs because "it seemed faster"

Standard linters won't catch this because the code is syntactically perfect.
SemantGuard catches it because the code is semantically wrong.

✨ Key Features

🚀 Quick Start (60 Seconds)

🚀 Quick Start (60 Seconds)

Note: SemantGuard repository is lightweight (~50MB). Models are downloaded separately only if you choose Local Mode.

1️⃣ Clone & Install

git clone https://github.com/yourusername/semantguard.git
cd semantguard
pip install -r requirements.txt

2️⃣ Choose Your Engine

Local Mode (Privacy-First):

# Install Ollama (one-time setup)
curl -fsSL https://ollama.com/install.sh | sh

### 3️⃣ Install Extension & Initialize

```bash
# Install VS Code extension
code --install-extension extension/semantguard-gatekeeper-2.3.8.vsix

Then in VS Code, click "Initialize Project" in the sidebar and choose a persona:

• 🚀 Solo-Indie: Focuses on clean naming and small functions
• 🏗️ Architect: Enforces DI and interface-driven design
• 🛡️ Fortress: Strict security, input sanitization, and statelessness Power Mode (Cloud-Based):

# Start server (no model download needed)
python start_server.py

# Then configure API key in VS Code extension
# Click ⚙️ Gear Icon → Configure API Key

3️⃣ Initialize

Click "Initialize Project" in the sidebar. Choose a persona:

• 🚀 Solo-Indie: Focuses on clean naming and small functions
• 🏗️ Architect: Enforces DI and interface-driven design
• 🛡️ Fortress: Strict security, input sanitization, and statelessness

🏛️ The "Six Pillars" Architecture

SemantGuard isn't just a prompt; it's a state machine. It tracks your project via:

.semantguard/
├── golden_state.md    # What is allowed
├── system_rules.md    # What is forbidden
├── task_logs.md       # Pending and completed work
└── resolutions.md     # Memory of past bugs (never fix them twice)

⚖️ Performance & Privacy

| Feature | Local Mode | Power Mode ⚡ | |---------|-----------|--------------| | Speed | 4-6s / audit | 0.5s - 1.5s / audit |

📦 Repository Size

Important: Model files are NEVER included in the Git repository. They are downloaded on-demand when you choose Local Mode and stored in Ollama's directory.

📦 Installation & SetupDeepSeek | Llama 4 Scout / Claude 3.5 |

📐 Architectural Integrity (Golden State)

Unlike traditional scanners that only hunt for bugs, SemantGuard enforces your Golden State—the core architectural plan of your project. It detects Context Drift before it becomes technical debt.

How It Works

1. Instruction: Place a golden_state.md in your .semantguard/ directory defining your "Must-Have" tools, frameworks, and patterns.

2. Enforcement: On every save, SemantGuard audits the diff against your plan.

3. The Result: If your plan mandates FastAPI but the AI suggests Flask, SemantGuard blocks the save and alerts you to the drift.

"Stop the loop. Guard the intent."

📦 Installation & Setup

Prerequisites

• VS Code 1.74.0 or higher
• Python 3.8+ (for local server)
• Ollama (for local mode) OR API key (for power mode)

Full Installation

# Clone the repository
git clone https://github.com/yourusername/semantguard.git
cd semantguard

# Install Python dependencies
pip install -r requirements.txt

# Start the local server (if using local mode)
python start_server.py

# Install the VS Code extension
code --install-extension extension/semantguard-gatekeeper-2.3.8.vsix

🎮 Usage

Basic Workflow

1. Write code in your AI IDE (Cursor, Windsurf, etc.)
2. Save the file (Ctrl+S / Cmd+S)
3. SemantGuard audits the changes against your rules
4. Accept or Reject based on the drift score

Drift Score Interpretation

• 🟢 0.0 - 0.3: Healthy (Auto-accept)
• 🟡 0.3 - 0.6: Warning (Review recommended)
• 🔴 0.6 - 1.0: Critical (Auto-reject)

🛠️ Configuration

Local Mode Setup

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull the model
ollama pull llama3.1:8b

# Start Ollama server
ollama serve

Power Mode Setup

1. Open SemantGuard sidebar
2. Click ⚙️ Settings
3. Select "Configure API Key"
4. Choose provider (Groq or OpenRouter)
5. Enter your API key

📚 Documentation

• Architecture Overview
• API Reference
• Contributing Guide
• Changelog

🤝 Get Involved

Built by Ethan Baron. If SemantGuard caught a drift for you, let me know!

• 🐦 X: @Jsaaaron91633
• 💼 LinkedIn: Ethan Baron
• 📧 Email: ethan.baron.home@gmail.com

📄 License

AGPLv3 — Keep it open.

This project is licensed under the GNU Affero General Public License v3.0. See LICENSE for details.

🌟 Star History

If SemantGuard helped you catch a drift, give us a star! ⭐